README

此库提供从数组参数中生成的查询构建器指令。此库旨在将 HTTP 请求中的过滤器应用于 API，以提供流畅的过滤和排序方言。

哲学

给定开发者识别了 A 和 B：A == B 关于过滤和排序实体数据的能力和愿望。

Doctrine 实体要共享的包含

id integer,
name string,
startAt datetime,
endAt datetime,

开发者 A 或 B 编写 API。资源是一个单一的 Doctrine 实体，数据使用 Doctrine QueryBuilder $objectManager->createQueryBuilder() 进行查询。此模块使其他开发者也能获得与 Doctrine 查询构建器相同的过滤和排序能力，但通过请求参数访问，就像 API 作者一样。例如，startAt between('2015-01-09', '2015-01-11'); 和 name like ('%arlie') 并非常见的手工编写 API 的过滤条件，也许没有此模块，API 作者会选择不实现它。有了这个模块的帮助，API 开发者可以轻松实现资源的复杂查询功能，而无需复杂的努力，从而保持 A == B。

安装

此模块的安装使用 composer。有关 composer 文档，请参阅 getcomposer.org。

$ php composer.phar require api-skeletons/zf-doctrine-orm-querybuilder ^1.0

安装后，将 ZF\Doctrine\ORM\QueryBuilder 添加到 config/application.config.php 中的模块列表中。

配置模块

将 config/zf-doctrine-orm-querybuilder.global.php.dist 复制到 config/autoload/zf-doctrine-orm-querybuilder.global.php 并编辑要启用的 invokables 列表。

与 Apigility Doctrine 一起使用

抽象查询提供者 ZF\Doctrine\ORM\QueryBuilder\Query\Provider\AbstractQueryProvider 有一个名为 applyFiltersAndOrderBy 的函数，它将向传递给它的 QueryBuilder 添加请求过滤和排序指令。

使用

配置示例

    'zf-doctrine-orm-querybuilder-orderby' => array(
        'invokables' => array(
            'field' => 'ZF\Doctrine\ORM\QueryBuilder\OrderBy\Field',
        ),
    ),
    'zf-doctrine-orm-querybuilder-filter' => array(
        'invokables' => array(
            'eq' => 'ZF\Doctrine\ORM\QueryBuilder\Filter\Equals',
        ),
    ),

PHP 语法中的示例请求。

$_GET = array(
    'filter' => array(
        array(
            'type' => 'eq',
            'field' => 'name',
            'value' => 'Tom',
        ),
    ),
    'order-by' => array(
        array(
            'type' => 'field',
            'field' => 'startAt',
            'direction' => 'desc',
        ),
    ),
);

过滤器

过滤器不是简单的键/值对。过滤器是一组无键的过滤器定义数组。每个过滤器定义是一个数组，数组值因过滤器类型而异。

每个过滤器定义至少需要一个 'type'。类型引用配置键，例如 'eq'、'neq'、'between'。

每个过滤器定义至少需要一个 'field'。这是目标实体上的字段名。

每个过滤器定义可以指定 'where'，其值为 'and' 或 'or'。

通过 AndX 和 OrX 过滤器类型支持嵌套逻辑，如 and(x or y)。

使用 jQuery 的一个 GET 查询示例

$(function() {
    $.ajax({
        url: "http://localhost:8081/api/resource-name",
        type: "GET",
        data: {
            'filter': [
            {
                'field': 'cycle',
                'where': 'or',
                'type': 'between',
                'from': '1',
                'to': '100'
            },
            {
                'field': 'cycle',
                'where': 'or',
                'type': 'gte',
                'value': '1000'
            }
        ]
        },
        dataType: "json"
    });
});

查询关系

单值

可以通过关系查询集合 - 只需提供关系名称作为 fieldName，标识符作为 value。

假设我们已定义了2个实体，User 和 UserGroup...

/**
 * @Entity
 */
class User {
    /**
     * @ManyToOne(targetEntity="UserGroup")
     * @var UserGroup
     */
    protected $group;
}

/**
 * @Entity
 */
class UserGroup {}

通过以下过滤器查询用户资源以找到属于 UserGroup id #1 的所有用户

    array('type' => 'eq', 'field' => 'group', 'value' => '1')

集合值

要匹配集合中具有实体B的实体A，请使用 ismemberof。假设 User 与 UserGroup 具有ManyToMany（或OneToMany）关联...

/**
 * @Entity
 */
class User {
    /**
     * @ManyToMany(targetEntity="UserGroup")
     * @var UserGroup[]|ArrayCollection
     */
    protected $groups;
}

通过以下过滤器查询用户资源以找到属于 UserGroup id #1 的所有用户

    array('type' => 'ismemberof', 'field' => 'groups', 'value' => '1')

日期字段格式

当日期字段参与过滤器时，您可以使用PHP日期格式化选项指定日期格式。默认日期格式为 Y-m-d H:i:s 如果您有一个只包含 Y-m-d 的日期字段，请将格式添加到过滤器中。有关完整的日期格式选项，请参阅 DateTime::createFromFormat

    'format' => 'Y-m-d',
    'value' => '2014-02-04',

连接实体和别名查询

包含内连接的过滤器，因此对于每种过滤器类型都有一个可选的 alias。默认别名为 'row'，表示REST资源的核心实体。没有过滤器可以添加其他实体到返回数据中。也就是说，默认情况下，只有原始目标资源 'row'，无论通过此模块应用了什么过滤器或排序，都会被返回。

默认情况下，zf-doctrine-orm-querybuilder.global.php.dist 不包含内连接

此示例通过在行实体上已定义的内连接连接报告字段，然后过滤 r.id = 2

    array('type' => 'innerjoin', 'field' => 'report', 'alias' => 'r'),
    array('type' => 'eq', 'alias' => 'r', 'field' => 'id', 'value' => '2')

您可以使用 parentAlias 从内连接连接表

    array('type' => 'innerjoin', 'parentAlias' => 'r', 'field' => 'owner', 'alias' => 'o'),

要启用内连接，请将以下内容添加到您的配置中

    'zf-doctrine-orm-querybuilder-filter' => array(
        'invokables' => array(
            'innerjoin' => 'ZF\Doctrine\ORM\QueryBuilder\Filter\InnerJoinFilter',
        ),
    ),

包含的过滤器类型

等于

array('type' => 'eq', 'field' => 'fieldName', 'value' => 'matchValue')

不等于

array('type' => 'neq', 'field' => 'fieldName', 'value' => 'matchValue')

小于

array('type' => 'lt', 'field' => 'fieldName', 'value' => 'matchValue')

小于或等于

array('type' => 'lte', 'field' => 'fieldName', 'value' => 'matchValue')

大于

array('type' => 'gt', 'field' => 'fieldName', 'value' => 'matchValue')

大于或等于

array('type' => 'gte', 'field' => 'fieldName', 'value' => 'matchValue')

为空

array('type' => 'isnull', 'field' => 'fieldName')

不为空

array('type' => 'isnotnull', 'field' => 'fieldName')

注意：In 和 NotIn 过滤器中的日期不按日期处理。建议您使用多个等于语句而不是这些过滤器来处理日期数据类型。

In

array('type' => 'in', 'field' => 'fieldName', 'values' => array(1, 2, 3))

NotIn

array('type' => 'notin', 'field' => 'fieldName', 'values' => array(1, 2, 3))

Between

array('type' => 'between', 'field' => 'fieldName', 'from' => 'startValue', 'to' => 'endValue')

Like (% 作为通配符)

array('type' => 'like', 'field' => 'fieldName', 'value' => 'like%search')

是成员

array('type' => 'ismemberof', 'field' => 'fieldName', 'value' => 1)

AndX

In AndX 查询中，conditions 是一个数组，包含此处描述的任何过滤器类型。连接始终是 and，因此条件中的 where 参数被忽略。AndX 过滤类型上的 where 参数不被忽略。

array(
    'type' => 'andx',
    'conditions' => array(
        array('field' =>'name', 'type'=>'eq', 'value' => 'ArtistOne'),
        array('field' =>'type', 'type'=>'eq', 'value' => 'Band'),
    ),
    'where' => 'and'
)

OrX

In OrX 查询中，conditions 是一个数组，包含此处描述的任何过滤器类型。连接始终是 or，因此条件中的 where 参数被忽略。OrX 过滤类型上的 where 参数不被忽略。

array(
    'type' => 'orx',
    'conditions' => array(
        array('field' =>'name', 'type'=>'eq', 'value' => 'ArtistOne'),
        array('field' =>'name', 'type'=>'eq', 'value' => 'ArtistTwo'),
    ),
    'where' => 'and'
)

包含的排序类型

字段

array('type' => 'field', 'field' => 'fieldName', 'direction' => 'desc');