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',
    ],
],

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

从版本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

此监听器连接到MvcEvent::EVENT_ROUTE事件，优先级为-650。它的目的是利用《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 注册。

rnd-cosoft / api-tools-content-validation

维护者

详细信息