README

这是一个用于 API Platform 的 Symfony 扩展包，用于添加基于 Symfony 表达式的强大过滤器，支持虚拟字段和可组合的过滤器。

升级

本版本适用于 API Platform 2.7 和 3.0，PHP 8.1 和 Symfony 6.1。如果您使用 API Platform 2.6、PHP 7.4 或 Symfony 5.4，则必须使用此包的 v1 版本。

在您继续之前

这是一个 WIP（工作进行中），因此您必须预期新版本发布时会有破坏性更改。此软件将尝试遵守 semver 规范（尝试不引入与新补丁版本不兼容的更改），但我不提供旧版本的支持。

范围

此扩展包不是

• 客户端表达式构建器。您必须事先定义属性和表达式。如果您需要，您可以使用 metaclass 的这个出色的扩展包（但它可能会在公共 API 中打开 DDoS 向量，请参阅此评论）。

安装

请确保已全局安装 Composer，如 Composer 文档的 安装章节 中所述。

使用 Symfony Flex 的应用程序

打开命令行，进入您的项目目录，然后执行以下命令

composer require instacar/extra-filters-bundle

就这些！您可以直接跳转到“配置”。

不使用 Symfony Flex 的应用程序

步骤 1：下载扩展包

打开命令行，进入您的项目目录，并执行以下命令以下载此扩展包的最新稳定版本

composer require instacar/extra-filters-bundle

步骤 2：启用扩展包

然后，通过将其添加到项目 config/bundles.php 文件中注册的扩展包列表中，来启用扩展包

// config/bundles.php

return [
    // ...
    Instacar\ExtraFiltersBundle\InstacarExtraFiltersBundle::class => ['all' => true],
];

配置

默认情况下，ExpressionFilter 启用了 API Platform 过滤器（不包括 OrderFilter），但您可以通过更新配置来启用自己的过滤器。示例

# config/packages/instacar_extra_filters.yml
instacar_extra_filters:
  doctrine:
    filters:
      App\Filter\CustomFilter: true

您还可以通过将过滤器设置为“false”来禁用 API Platform 的过滤器，用于 ExpressionFilter。示例（所有可用过滤器）

# config/packages/instacar_extra_filters.yml
instacar_extra_filters:
  doctrine:
    filters:
      ApiPlatform\Doctrine\Orm\Filter\SearchFilter: false
      ApiPlatform\Doctrine\Orm\Filter\RangeFilter: false
      ApiPlatform\Doctrine\Orm\Filter\DateFilter: false
      ApiPlatform\Doctrine\Orm\Filter\BooleanFilter: false
      ApiPlatform\Doctrine\Orm\Filter\NumericFilter: false
      ApiPlatform\Doctrine\Orm\Filter\ExistsFilter: false

使用方法

您可以将 ExpressionFilter 实现为 API Platform 的正常过滤器。例如

// src/Entity/Book.php

use ApiPlatform\Metadata\ApiFilter;
use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
use Doctrine\ORM\Mapping as ORM;
use Instacar\ExtraFiltersBundle\Doctrine\Orm\Filter\ExpressionFilter;

#[ApiResource]
#[ApiFilter(ExpressionFilter::class, properties: [
    'search' => 'orWhere(search("name", "partial"), search("author.name", "partial"), search("year", "partial"))',
])]
#[ORM\Entity]
class Book {
    // real implementation
}

表达式语法如下

['filter-property' => 'operator(filter1(property, strategy, value), filter2(property, strategy, value), ..., filterN(property, strategy, value))'];

其中

• filter-property: 在您的 API 中用于过滤的属性。您可以使用虚拟属性（不在实体中存在的属性）。
• operator: 一个 支持的运算符。
• filter: 一个 支持的过滤器。
• property: 实体中的属性名称。如果您想使用与 filter-property 相同的名称，可以使用 "property"。
• strategy: 过滤器文档中记录的值。可选。您可以使用 "null" 来使用后续参数。
• 值: 传递给过滤器的值。可选。您可以使用此属性在传递给过滤器之前操纵该值，例如，使用 DateFilter，您可以使用 {before: value} 搜索旧日期。

允许的值

• 用户: 等于当前 Symfony 用户。
• 令牌: 等于当前 Symfony 安全令牌。

支持的运算符

• andWhere: 等于 SQL 运算符 "AND"。
• orWhere: 等于 SQL 运算符 "OR"。
• notWhere: 等于 SQL 运算符 "NOT"。

支持的过滤器

• 所有 API Platform 的 ORM 过滤器（目前测试了 SearchFilter 和 DateFilter）。
• 实现 ORM 的 FilterInterface 接口的自定义过滤器。注意：表达式中过滤器的名称采用驼峰式命名，不带 "Filter" 后缀（例如，SearchFilter 转换为 search）。

限制

• 它仅适用于 ORM 过滤器。
• 它不会为 API Platform 生成定制文档，它仅生成一个具有 "string" 值的通用属性。

未来工作

这是我为这个包所想的一些想法。如果您有其他想法，请在 "问题" 选项卡中告诉我。

• 使用此过滤器与工作 ODM 过滤器。

许可

此包根据 GNU LGPLv3 许可。有关此许可证权限的快速摘要，请参阅 GNU LGPLv3，在 choosealicense.com。

有关更多详细信息，请参阅 LICENSE 文件。