README

PHP 类库，允许轻松构建和扩展 OData 查询，以附加到支持 OData v4.0 的服务器端 API。此库支持的任何查询函数均基于 API 服务器的配置。此库仅符合在 http://www.odata.org/ 上描述的预期功能。此库的其他语言版本可在 http://www.odata.org/libraries 或 GitHub 上 https://github.com/ODataOrg/ 获取。

安装

使用 Composer 包含在 PHP 项目中

使用最新版本号或 1.0.* 将以下内容添加到您的 composer.json 文件中，以保持其最新

"require": {
    "curiosity26/odataquery": "1.0.*"
}

或使用最新的开发版本

"require": {
    "curiosity26/odataquery": "dev-master"
}

独立项目

安装 composer 后，使用您的命令行终端并 cd 进入 ODataQuery-PHP 文件夹。运行 'composer install'。如果您正确安装了 composer，它应该可以正常工作，并会创建一个新的名为 'vendors' 的目录。在 vendors 文件夹中，有一个由 composer 创建的 autoload.php 文件。

基本用法

在加载自己的代码模块或任何使用 ODataQuery-PHP 的脚本时包含此自动加载器。

$autoloader = "/path/to/ODataQuery-PHP/vendor/autoload.php";
require_once $autoloader;

示例

我们的基础 API URL

$apiUrl = "http://www.example.com/test/api/";

首先，我们将为对象的请求构建一个路径。（示例中会隐含命名空间。假设您正在使用 IDE 和 composer 创建的自动加载器，这些将为您自动填充。）

$property = 'Employees';
$path = new ODataResourcePath($apiUrl.$property);

创建的路径可以像字符串变量一样使用

print $path;
// http://www.example.com/test/api/Employees

如果您需要强制将路径用作字符串（有时在将参数传递给需要字符串参数的函数时很有用），您只需将 ODataResourcePath 对象转换为字符串即可。这对 ODataQuery 库中的任何对象都适用。

myFakeFunction((string)$path);

$select

您可以选择包含在返回对象中的属性

$path->setSelect(new ODataQuerySelect(array("FirstName", "LastName")));

请参阅下面的展开部分，了解如何将 select 应用于特定属性。

$search

您可以使用搜索搜索对象集中的属性

$path->setSearch(new ODataQuerySearch('mountain bike'));

搜索查询也是可链式的

$search = $path->getSearch(); 
// operations functions are both setters and getters. When setting, the funciton returns the $path object for chainability
$search->_and('balloon');
$path->setSearch($search);

现在将搜索返回的 Employees 对象集，以 '"mountain bike" AND balloon'。请参阅下面的展开部分，了解如何将搜索函数应用于特定属性。

$count

您可以返回查询的总记录数。$count 系统查询选项忽略任何 $top、$skip 或 $expand 查询选项，并返回跨所有页面的结果总数，包括仅匹配任何指定的 $filter 和 $search 的结果。客户端应意识到，内联返回的计数可能不等于实际的项目数，这可能是由于计算计数和枚举最后一个值之间的延迟，或者由于服务上的计算不精确。

$path->getCount();
$path->setCount(FALSE); // Disables $count

$filter

查询的记录集可以进行筛选，以返回更精确的记录集。有多种筛选器可供选择，并且大多数可以与其他筛选器结合使用。

$filter = new ODataGreaterThanEqualsFilter('YearsEmployed', 6); // YearsEmployed ge 6
$path->setFilter($filter);

每个筛选器都有一组可扩展的函数，这些函数允许筛选器被传递到另一个筛选器中，从而返回新的筛选器。

$add_filter = new ODataAddFilter('YearsEmployed', 5); // YearsEmployed add 5
$filter = $add_filter->greaterThanEquals(6); // YearsEmployed add 5 ge 6
$path->setFilter($filter);

筛选器可以接受筛选器作为属性或值，值也可以是属性名。

$sub_filter = new ODataSubtractFilter('YearsEmployed', 'YearsSebatical'); // YearsEmployed sub YearsSebatical
$sub_filter2 = new ODataAddFilter('Awards', 'Demotions'); // Awards sub Demotions
$filter = $sub_filter->greaterThan($sub_filter2); // (YearsEmployed sub YearsSebatical) gt (Awards sub Demotions)
$path->setFilter($filter);

$pager

可以通过传递 $top 和 $skip 在服务器端分页记录，其中 $top 是返回的记录数限制，$skip 是开始偏移量。ODataQueryPager 对象从等式中去除数学计算，并允许您简单地指定限制和要返回的页面。

$pager = new ODataQueryPager(20, 5); // $top=20&$skip=100
$path->setPager($pager);

$orderby

可以在集合内按属性名对结果进行排序。只需在 orderBy() 函数中指定要排序的属性即可。

$path->setOrderBy('LastName');

$expand

ODataQueryExpand 对象用于对主查询的结果进行子查询。它可以使用 OData 的路径格式（Property1/SubProperty1/AndSoOn）应用于主查询记录集的属性，或应用于扩展的属性（深度注入）。

ODataQueryExpand 对象与 ODataResourcePath 的父类相同；ODataResource。因此，所有上述函数都在 ODataQueryExpand 对象上可用，包括 expand，它允许扩展的属性对自己进行扩展（深度注入）。

由于可以扩展多个属性，ODataResourcePath 和 ODataQueryExpand 的 expand() 函数需要一个 ODataExpandableInterface 对象的集合，形式为一个单独的 ODataQueryExpandCollection 对象。必须将 ODataQueryExpand 对象添加到 ODataQueryExpandCollection 中，然后将其传递给 ODataResourcePath 或 ODataQueryExpand 对象。

$collection = new ODataQueryExpandCollection();

$expand1 = new ODataQueryExpand('FirstName'); // Expand upon the FirstName property
$filter = new ODataEqualsFilter('$it', "'Alex'"); // Only string filter functions safely wrap strings. Other filters can't distinguish between a regular string function or a property name
$expand1->filter($filter);
$collection->add($expand1);

$expand2 = new ODataQueryExpand('LastName'); // Expand upon the LastName property
$search = new ODataQuerySearch("Boyce");
$expand2->search($search); // Search the last name
$collection->add($expand2);

$expand3 = new ODataQueryExpand('Address');
$expand4 = new ODataQueryExpand('City'); // Assuming the Address is an object containing City and not a sibling of City
$search2 = new ODataQuerySearch('New York');
$expand4->search($search2);
$expand3->expand(new ODataQueryExpandCollection(array($expand4))); // Add $expand4 to $expand3, wrapping it in a collection
$collection->add($expand3);

$path->expand($collection);

// OUTPUT PATH: http://www.example.com/test/api/Employees?$expand=FirstName($filter=$it eq 'Alex'),LastName($search=Boyce),Address($expand=City($search="New York"))

仅资源路径

参数

参数可以用于替换任何查询对象的任何属性或值。使用变量时，在变量名前加 '@'。使用 ODataQueryParameterCollection 对象，并设置参数，就像在对象上设置公共变量一样。

$params = new ODataQueryParameterCollection();
$params->myParam1 = 10;
$params->otherParam = "Other";

$filter = new ODataLessThanEquals('@otherPraram', '@myParam1');

$path->filter($filter)->parameters($params);

// OUTPUT PATH: http://www.example.com/test/api/Employees?$filter=@otherParam le @myParam1&@myParam1=10&@otherParam=Other