README

🇷🇺 俄罗斯公民

我们是Laminas的参与者，来自不同的国家。我们中许多人都有在俄罗斯和乌克兰的朋友、亲戚和同事。我们中的一些人出生在俄罗斯。我们中的一些人现在住在俄罗斯。我们中的一些人的祖父母在第二次世界大战中与法西斯战斗过。在这里，没有人支持法西斯主义。

我们中的一位成员有一个乌克兰亲戚，她和儿子一起从家里逃了出来。火车因前方道路上的轰炸而延误。我们有朋友躲在防空洞里。我们在空袭后焦急地等待他们的消息，空袭无差别地向医院、学校、幼儿园和房屋开火。我们不是从任何媒体上得知这些的。这是我们亲眼所见。

您足够信任我们，使用我们的程序，我们请求您再次信任我们。我们需要帮助。走出去，抗议这场毫无意义的战争。停止流血。说“不，战争！”

🇺🇸 致俄罗斯公民

我们Laminas来自世界各地。我们中许多人有在俄罗斯和乌克兰的朋友、家人和同事。我们中的一些人出生在俄罗斯。我们中的一些人现在住在俄罗斯。我们中的一些人的祖父母在第二次世界大战中与纳粹战斗过。在这里，没有人支持法西斯主义。

我们的团队成员中有一位乌克兰亲戚，她和儿子一起逃离了家园。火车因前方道路上的轰炸而延误。我们有朋友躲在防空洞里。我们在空袭后焦急地等待他们的消息，空袭无差别地向医院、学校、幼儿园和房屋开火。我们不是从任何媒体上得知这些的。这是我们亲身经历。

您足够信任我们，使用我们的软件。我们请求您在这件事上信任我们。我们需要您的帮助。走出去，抗议这场不必要的战争。停止流血。说“停止战争！”

简介

Laminas模块，用于自动化验证传入的输入。

允许以下操作

• 定义命名的输入过滤器。
• 将命名的输入过滤器映射到命名的控制器服务。
• 对于无效的输入返回带有验证错误消息的 ApiProblemResponse。

需求

请参阅 composer.json 文件。

安装

运行以下 composer 命令

$ composer require laminas-api-tools/api-tools-content-validation

或者，手动将以下内容添加到您的 composer.json 文件中的 require 部分

"require": {
    "laminas-api-tools/api-tools-content-validation": "^1.4"
}

然后运行 composer update 以确保模块已安装。

最后，将模块名称添加到项目 config/application.config.php 文件中的 modules 键下

return [
    /* ... */
    'modules' => [
        /* ... */
        'Laminas\ApiTools\ContentValidation',
    ],
    /* ... */
];

配置

用户配置

此模块使用两个用户级配置键 api-tools-content-validation 和 input_filter_specs（命名方式使得此功能将来可以移入Laminas）。

服务名称键

api-tools-content-validation 键是控制器服务名称到值的映射，其中值是一个数组，用于确定对给定请求响应的 HTTP 方法以及将映射到什么输入过滤器。映射的键可以是接受请求体的 HTTP 方法（即 POST、PUT、PATCH 或 DELETE），或者它是单词 input_filter。分配给 input_filter 键的值将在当前 HTTP 请求方法没有配置输入过滤器的情况下使用。

具有默认值和 POST 过滤器的示例

'api-tools-content-validation' => [
    'Application\Controller\HelloWorld' => [
        'input_filter' => 'Application\Controller\HelloWorld\Validator',
        'POST' => 'Application\Controller\HelloWorld\CreationValidator',
    ],
],

在上面的示例中，Application\Controller\HelloWorld\Validator 服务将为 PATCH、PUT 或 DELETE 请求选择，而 Application\Controller\HelloWorld\CreationValidator 将为 POST 请求选择。

从版本 1.1.0 开始，可以定义两个额外的键来影响应用程序验证行为

• use_raw_data：如果不存在，原始数据始终注入到“BodyParams”容器中（由 api-tools-content-negotiation 定义）。如果此键存在且为布尔值 false，则将使用来自输入过滤器的已验证、过滤后的数据。

• allows_only_fields_in_filter：如果存在，且 use_raw_data 为布尔值 false，则此标志的值将定义是否将有效载荷中存在的其他字段与过滤后的数据合并。

• remove_empty_data：是否应从接收到的数据中删除空数据？

  • 如果没有 remove_empty_data 标志，则不执行任何操作 - 使用数据原样
  • 如果 remove_empty_data 标志存在且为布尔值 true，则从当前数据数组中删除空数据
  • 如果键与接收到的数据匹配，则不删除空数据

验证 GET 请求

• 自 1.3.0 版本以来。

从 1.3.0 版本开始，您可以指定 GET 作为 HTTP 方法，将其映射到输入过滤器以验证查询参数。配置方式与上述部分中描述的完全相同。

此功能仅在手动配置 API 时可用；它不在 Admin UI 中公开。

验证集合请求

• 自 1.5.0 版本以来。

从 1.5.0 版本开始，您可以指定以下任一作为键：

• POST_COLLECTION
• PUT_COLLECTION
• PATCH_COLLECTION

这些键将专门用于给定的 HTTP 方法，但仅对匹配集合端点的请求。

验证 DELETE 请求

• 自 1.6.0 版本以来。

从 1.6.0 版本开始，您可以指定以下每个键作为输入过滤器：

• DELETE
• DELETE_COLLECTION

与键关联的输入过滤器将用于验证请求体中的数据。

input_filter_spec

input_filter_spec 用于由配置驱动的输入过滤器创建。此数组的键将是一个唯一名称，但更常见的是基于它在 api-tools-content-validation 键下映射的服务名称。值将是输入过滤器配置数组，如 Laminas 手册中关于输入过滤器的部分所述。

示例

'input_filter_specs' => [
    'Application\Controller\HelloWorldGet' => [
        0 => [
            'name' => 'name',
            'required' => true,
            'filters' => [
                0 => [
                    'name' => 'Laminas\Filter\StringTrim',
                    'options' => [],
                ],
            ],
            'validators' => [],
            'description' => 'Hello to name',
            'allow_empty' => false,
            'continue_if_empty' => false,
        ],
    ],

系统配置

以下配置由模块定义，以便在 Laminas 应用程序中运行。

namespace Laminas\ApiTools\ContentValidation;

use Laminas\InputFiler\InputFilterAbstractServiceFactory;
use Laminas\ServiceManager\Factory\InvokableFactory;

return [
    'controller_plugins' => [
        'aliases' => [
            'getinputfilter' => InputFilter\InputFilterPlugin::class,
            'getInputfilter' => InputFilter\InputFilterPlugin::class,
            'getInputFilter' => InputFilter\InputFilterPlugin::class,
        ],
        'factories' => [
            InputFilter\InputFilterPlugin::class => InvokableFactory::class,
        ],
    ],
    'input_filters' => [
        'abstract_factories' => [
            InputFilterAbstractServiceFactory::class,
        ],
    ],
    'service_manager' => [
        'factories' => [
            ContentValidationListener::class => ContentValidationListenerFactory::class,
        ],
    ],
    'validators' => [
        'factories' => [
            'Laminas\ApiTools\ContentValidation\Validator\DbRecordExists' => Validator\Db\RecordExistsFactory::class,
            'Laminas\ApiTools\ContentValidation\Validator\DbNoRecordExists' => Validator\Db\NoRecordExistsFactory::class,
        ],
    ],
];

Laminas 事件

监听器

Laminas\ApiTools\ContentValidation\ContentValidationListener

此监听器附加到优先级为 -650 的 MvcEvent::EVENT_ROUTE 事件。其目的是利用 api-tools-content-validation 配置来确定当前请求所选控制器服务名称是否配置了输入过滤器。如果是，它将遍历配置文件中的映射，创建适当的输入过滤器（来自配置或 Laminas 输入过滤器插件管理器），以验证传入的数据。这个特定的监听器利用 api-tools-content-negotiation 数据容器中的数据来获取反序列化的内容主体参数。

事件

Laminas\ApiTools\ContentValidation\ContentValidationListener::EVENT_BEFORE_VALIDATE

此事件由 Laminas\ApiTools\ContentValidation\ContentValidationListener::onRoute()（如上所述）在聚合要验证的数据和确定输入过滤器之间以及实际数据验证时发出。其目的是允许用户

• 操作输入过滤器。
• 修改要验证的数据集（自 1.4.0 版本以来可用）。

例如，您可能想验证通过 URI 提供的标识符，并在路由过程中匹配。您可以这样做：

$events->listen(ContentValidationListener::EVENT_BEFORE_VALIDATE, function ($e) {
    if ($e->getController() !== MyRestController::class) {
        return;
    }

    $matches = $e->getRouteMatch();
    $data = $e->getParam('Laminas\ApiTools\ContentValidation\ParameterData') ?: [];
    $data['id'] = $matches->getParam('id');
    $e->setParam('Laminas\ApiTools\ContentValidation\ParameterData', $data);
});

Laminas 服务

控制器插件

Laminas\ApiTools\ContentValidation\InputFilter\InputFilterPlugin（即 getInputFilter）

此插件对 Laminas 控制器可用。当调用时（$this->getInputFilter() 或 $this->plugin('getinputfilter')->__invoke()），它返回 MVC 事件参数 Laminas\ApiTools\ContentValidation\InputFilter 中的内容，对于任何不是 Laminas\InputFilter\InputFilter 实现的值返回 null。

服务

Laminas\InputFilter\InputFilterAbstractServiceFactory

此抽象工厂负责根据名称和顶级键 input_filter_specs 的配置创建并返回适当的输入过滤器。它已注册到 Laminas\InputFilter\InputFilterPluginManager。