laminas-api-tools / api-tools-content-validation
Laminas module providing incoming content validation
Fund package maintenance!
Community Bridge
Installs: 1 215 934
Dependents: 3
Suggesters: 0
Security: 0
Stars: 7
Watchers: 10
Forks: 14
Open Issues: 9
Requires
- php: ~8.0.0 || ~8.1.0 || ~8.2.0
- laminas-api-tools/api-tools-api-problem: ^1.6
- laminas-api-tools/api-tools-content-negotiation: ^1.8
- laminas/laminas-eventmanager: ^2.6.3 || ^3.0.1
- laminas/laminas-filter: ^2.7.1
- laminas/laminas-http: ^2.5.4
- laminas/laminas-inputfilter: ^2.8
- laminas/laminas-mvc: ^2.7.15 || ^3.0.4
- laminas/laminas-servicemanager: ^3.11
- laminas/laminas-stdlib: ^3.2.1
- laminas/laminas-validator: ^2.8.1
- laminas/laminas-zendframework-bridge: ^1.0
Requires (Dev)
- laminas/laminas-coding-standard: ~2.3.0
- laminas/laminas-db: ^2.8.1
- phpspec/prophecy-phpunit: ^2.0
- phpunit/phpunit: ^9.5.10
- psalm/plugin-phpunit: ^0.16.0
- vimeo/psalm: ^4.7
Replaces
- zfcampus/zf-content-validation: ^1.8.0
This package is auto-updated.
Last update: 2024-09-11 15:24:04 UTC
README
π·πΊ Π ΡΡΡΠΊΠΈΠΌ Π³ΡΠ°ΠΆΠ΄Π°Π½Π°ΠΌ
ΠΡ, ΡΡΠ°ΡΡΠ½ΠΈΠΊΠΈ Laminas, ΡΠΎΠ΄ΠΈΠ»ΠΈΡΡ ΠΈ ΠΆΠΈΠ²Π΅ΠΌ Π² ΡΠ°Π·Π½ΡΡ ΡΡΡΠ°Π½Π°Ρ . Π£ ΠΌΠ½ΠΎΠ³ΠΈΡ ΠΈΠ· Π½Π°Ρ Π΅ΡΡΡ Π΄ΡΡΠ·ΡΡ, ΡΠΎΠ΄ΡΡΠ²Π΅Π½Π½ΠΈΠΊΠΈ ΠΈ ΠΊΠΎΠ»Π»Π΅Π³ΠΈ ΠΊΠ°ΠΊ Π² Π ΠΎΡΡΠΈΠΈ, ΡΠ°ΠΊ ΠΈ Π² Π£ΠΊΡΠ°ΠΈΠ½Π΅. ΠΠ΅ΠΊΠΎΡΠΎΡΡΠ΅ ΠΈΠ· Π½Π°Ρ ΡΠΎΠ΄ΠΈΠ»ΠΈΡΡ Π² Π ΠΎΡΡΠΈΠΈ. ΠΠ΅ΠΊΠΎΡΠΎΡΡΠ΅ ΠΈΠ· Π½Π°Ρ ΠΆΠΈΠ²ΡΡ Π² Π ΠΎΡΡΠΈΠΈ. Π£ Π½Π΅ΠΊΠΎΡΠΎΡΡΡ Π±Π°Π±ΡΡΠΊΠΈ ΠΈ Π΄Π΅Π΄ΡΡΠΊΠΈ ΡΡΠ°ΠΆΠ°Π»ΠΈΡΡ Ρ ΡΠ°ΡΠΈΡΡΠ°ΠΌΠΈ Π²ΠΎ ΠΡΠΎΡΠΎΠΉ ΠΌΠΈΡΠΎΠ²ΠΎΠΉ Π²ΠΎΠΉΠ½Π΅. ΠΠ΄Π΅ΡΡ Π½ΠΈΠΊΡΠΎ Π½Π΅ ΠΏΠΎΠ΄Π΄Π΅ΡΠΆΠΈΠ²Π°Π΅Ρ ΡΠ°ΡΠΈΠ·ΠΌ.
Π£ ΠΎΠ΄Π½ΠΎΠ³ΠΎ ΠΈΠ· Π½Π°Ρ Π΅ΡΡΡ ΡΠΊΡΠ°ΠΈΠ½ΡΠΊΠ°Ρ ΡΠΎΠ΄ΡΡΠ²Π΅Π½Π½ΠΈΡΠ°, ΠΊΠΎΡΠΎΡΠ°Ρ ΡΠΏΠ°ΡΠ»Π°ΡΡ ΠΈΠ· Π΄ΠΎΠΌΠ° Π²ΠΌΠ΅ΡΡΠ΅ Ρ ΡΡΠ½ΠΎΠΌ. ΠΠΎΠ΅Π·Π΄ Π·Π°Π΄Π΅ΡΠΆΠ°Π»ΡΡ ΠΈΠ·-Π·Π° Π±ΠΎΠΌΠ±Π΅ΠΆΠΊΠΈ Π½Π° Π΄ΠΎΡΠΎΠ³Π΅ Π²ΠΏΠ΅ΡΠ΅Π΄ΠΈ. Π£ Π½Π°Ρ Π΅ΡΡΡ Π΄ΡΡΠ·ΡΡ, ΠΊΠΎΡΠΎΡΡΠ΅ ΠΏΡΡΡΡΡΡΡ Π² Π±ΠΎΠΌΠ±ΠΎΡΠ±Π΅ΠΆΠΈΡΠ°Ρ . ΠΡ Ρ ΡΡΠ΅Π²ΠΎΠ³ΠΎΠΉ ΠΆΠ΄Π΅ΠΌ Π²Π΅ΡΡΠΎΡΠΊΠΈ ΠΎΡ Π½ΠΈΡ ΠΏΠΎΡΠ»Π΅ Π²ΠΎΠ·Π΄ΡΡΠ½ΡΡ Π½Π°Π»Π΅ΡΠΎΠ², ΠΊΠΎΡΠΎΡΡΠ΅ Π±Π΅ΡΠΏΠΎΡΡΠ΄ΠΎΡΠ½ΠΎ Π½Π°Π½ΠΎΡΡΡ ΡΠ΄Π°ΡΡ ΠΈ ΠΏΠΎΠΏΠ°Π΄Π°ΡΡ ΠΏΠΎ Π±ΠΎΠ»ΡΠ½ΠΈΡΠ°ΠΌ, ΡΠΊΠΎΠ»Π°ΠΌ, Π΄Π΅ΡΡΠΊΠΈΠΌ ΡΠ°Π΄Π°ΠΌ ΠΈ Π΄ΠΎΠΌΠ°ΠΌ. ΠΡ Π½Π΅ Π±Π΅ΡΠ΅ΠΌ ΡΡΠΎ ΠΈΠ· ΠΊΠ°ΠΊΠΈΡ -Π»ΠΈΠ±ΠΎ Π‘ΠΠ. ΠΡ Π½Π°Π±Π»ΡΠ΄Π°Π΅ΠΌ ΡΡΠΎ Π½Π°ΠΏΡΡΠΌΡΡ.
ΠΡ Π΄ΠΎΠ²Π΅ΡΡΠ΅ΡΠ΅ Π½Π°ΠΌ Π΄ΠΎΡΡΠ°ΡΠΎΡΠ½ΠΎ, ΡΡΠΎΠ± ΠΈΡΠΏΠΎΠ»ΡΠ·ΠΎΠ²Π°ΡΡ Π½Π°ΡΠΈ ΠΏΡΠΎΠ³ΡΠ°ΠΌΠΌΡ, ΠΈ ΠΌΡ ΠΏΡΠΎΡΠΈΠΌ Π²Π°Ρ Π΄ΠΎΠ²Π΅ΡΠΈΡΡΡΡ Π½Π°ΠΌ Π²Π½ΠΎΠ²Ρ. ΠΡ Π½ΡΠΆΠ΄Π°Π΅ΠΌΡΡ Π² ΠΏΠΎΠΌΠΎΡΠΈ. ΠΡΡ ΠΎΠ΄ΠΈΡΠ΅ ΠΈ ΠΏΡΠΎΡΠ΅ΡΡΡΠΉΡΠ΅ ΠΏΡΠΎΡΠΈΠ² ΡΡΠΎΠΉ Π±Π΅ΡΠΏΠΎΠ»Π΅Π·Π½ΠΎΠΉ Π²ΠΎΠΉΠ½Ρ. ΠΡΡΠ°Π½ΠΎΠ²ΠΈΡΠ΅ ΠΊΡΠΎΠ²ΠΎΠΏΡΠΎΠ»ΠΈΡΠΈΠ΅. Π‘ΠΊΠ°ΠΆΠΈΡΠ΅ "ΠΠ΅Ρ Π²ΠΎΠΉΠ½Π΅!"
πΊπΈ To Citizens of Russia
We at Laminas come from all over the world. Many of us have friends, family and colleagues in both Russia and Ukraine. Some of us were born in Russia. Some of us currently live in Russia. Some have grandparents who fought Nazis in World War II. Nobody here supports fascism.
One team member has a Ukrainian relative who fled her home with her son. The train was delayed due to bombing on the road ahead. We have friends who are hiding in bomb shelters. We anxiously follow up on them after the air raids, which indiscriminately fire at hospitals, schools, kindergartens and houses. We're not taking this from any media. These are our actual experiences.
You trust us enough to use our software. We ask that you trust us to say the truth on this. We need your help. Go out and protest this unnecessary war. Stop the bloodshed. Say "stop the war!"
Introduction
Laminas module for automating validation of incoming input.
Allows the following:
- Defining named input filters.
- Mapping named input filters to named controller services.
- Returning an
ApiProblemResponse
with validation error messages on invalid input.
Requirements
Please see the composer.json file.
Installation
Run the following composer
command:
$ composer require laminas-api-tools/api-tools-content-validation
Alternately, manually add the following to your composer.json
, in the require
section:
"require": { "laminas-api-tools/api-tools-content-validation": "^1.4" }
And then run composer update
to ensure the module is installed.
Finally, add the module name to your project's config/application.config.php
under the modules
key:
return [ /* ... */ 'modules' => [ /* ... */ 'Laminas\ApiTools\ContentValidation', ], /* ... */ ];
Configuration
User Configuration
This module utilizes two user level configuration keys api-tools-content-validation
and also
input_filter_specs
(named such that this functionality can be moved into Laminas in the future).
Service Name key
The api-tools-content-validation
key is a mapping between controller service names as the key, and the
value being an array of mappings that determine which HTTP method to respond to and what input
filter to map to for the given request. The keys for the mapping can either be an HTTP method that
accepts a request body (i.e., POST
, PUT
, PATCH
, or DELETE
), or it can be the word
input_filter
. The value assigned for the input_filter
key will be used in the case that no input
filter is configured for the current HTTP request method.
Example where there is a default as well as a POST filter:
'api-tools-content-validation' => [ 'Application\Controller\HelloWorld' => [ 'input_filter' => 'Application\Controller\HelloWorld\Validator', 'POST' => 'Application\Controller\HelloWorld\CreationValidator', ], ],
In the above example, the Application\Controller\HelloWorld\Validator
service will be selected for
PATCH
, PUT
, or DELETE
requests, while the Application\Controller\HelloWorld\CreationValidator
will be selected for POST
requests.
Starting in version 1.1.0, two additional keys can be defined to affect application validation behavior:
-
use_raw_data
: if NOT present, raw data is ALWAYS injected into the "BodyParams" container (defined by api-tools-content-negotiation). If this key is present and a boolean false, then the validated, filtered data from the input filter will be used instead. -
allows_only_fields_in_filter
: if present, anduse_raw_data
is boolean false, the value of this flag will define whether or not additional fields present in the payload will be merged with the filtered data. -
remove_empty_data
: Should we remove empty data from received data?- If no
remove_empty_data
flag is present, do nothing - use data as is - If
remove_empty_data
flag is present AND is boolean true, then remove empty data from current data array - Does not remove empty data if keys matched received data
- If no
Validating GET requests
- Since 1.3.0.
Starting in 1.3.0, you may also specify
GET
as an HTTP method, mapping it to an input filter in order to validate your query parameters. Configuration is exactly as described in the above section.This feature is only available when manually configuring your API; it is not exposed in the Admin UI.
Validating collection requests
- Since 1.5.0
Starting in 1.5.0, you may specify any of:
POST_COLLECTION
PUT_COLLECTION
PATCH_COLLECTION
as keys. These will then be used specifically with the given HTTP method, but only on requests matching the collection endpoint.
Validating DELETE requests
- Since 1.6.0
Starting in 1.6.0, you may specify each of the following keys for input filters:
DELETE
DELETE_COLLECTION
The input filter associated with the key will be used to validate data sent in the request body.
input_filter_spec
input_filter_spec
is for configuration-driven creation of input filters. The keys for this array
will be a unique name, but more often based off the service name it is mapped to under the
api-tools-content-validation
key. The values will be an input filter configuration array, as is
described in the Laminas manual section on input
filters.
Example:
'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, ], ],
System Configuration
The following configuration is defined by the module in order to function within a Laminas application.
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 Events
Listeners
Laminas\ApiTools\ContentValidation\ContentValidationListener
This listener is attached to the MvcEvent::EVENT_ROUTE
event at priority -650
. Its purpose is
to utilize the api-tools-content-validation
configuration in order to determine if the current request's
selected controller service name has a configured input filter. If it does, it will traverse the
mappings from the configuration file to create the appropriate input filter (from configuration or
the Laminas input filter plugin manager) in order to validate the incoming data. This
particular listener utilizes the data from the api-tools-content-negotiation
data container in order to
get the deserialized content body parameters.
Events
Laminas\ApiTools\ContentValidation\ContentValidationListener::EVENT_BEFORE_VALIDATE
This event is emitted by Laminas\ApiTools\ContentValidation\ContentValidationListener::onRoute()
(described above) in between aggregating data to validate and determining the
input filter, and the actual validation of data. Its purpose is to allow users:
- the ability to manipulate input filters.
- to modify the data set to validate (available since 1.4.0).
As an example, you might want to validate an identifier provided via the URI, and matched during routing. You may do this as follows:
$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 Services
Controller Plugins
Laminas\ApiTools\ContentValidation\InputFilter\InputFilterPlugin (aka getInputFilter)
This plugin is available to Laminas controllers. When invoked ($this->getInputFilter()
or
$this->plugin('getinputfilter')->__invoke()
), it returns whatever is in the MVC event parameter
Laminas\ApiTools\ContentValidation\InputFilter
, returning null for any value that is not an implementation of
Laminas\InputFilter\InputFilter
.
Service
Laminas\InputFilter\InputFilterAbstractServiceFactory
This abstract factory is responsible for creating and returning an appropriate input filter given
a name and the configuration from the top-level key input_filter_specs
. It is registered with
Laminas\InputFilter\InputFilterPluginManager
.