diff --git a/Configuration/Testing/Validation.yaml b/Configuration/Testing/Validation.yaml index 45d895e..d24fcc2 100644 --- a/Configuration/Testing/Validation.yaml +++ b/Configuration/Testing/Validation.yaml @@ -16,12 +16,12 @@ TrueValidator: DigiComp\SettingValidator\Tests\Functional\Fixtures\TestValidationGroupsCustomObject: self: DigiComp.SettingValidator:Settings: - name: 'GroupValidatorCustom' + name: "GroupValidatorCustom" DigiComp\SettingValidator\Tests\Functional\Fixtures\TestValidationGroupsDefaultObject: self: DigiComp.SettingValidator:Settings: - name: 'GroupValidatorDefault' + name: "GroupValidatorDefault" GroupValidatorDefault: properties: @@ -35,4 +35,4 @@ GroupValidatorCustom: BooleanValue: expectedValue: false validationGroups: - - 'Custom' + - "Custom" diff --git a/README.md b/README.md index fc438b7..02e434d 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,211 @@ # DigiComp.SettingValidator -This Package allows configuring Validators for your Action-Arguments or domain model properties to be set by a new -Yaml-File in your Configuration directory. +This package allows configuring validators with a new configuration type. -Let's imagine you had this action-method: +## Introduction - /** - * @Flow\Validate(argumentName="order", type="DigiComp.SettingValidator:Settings") - * @param Order $order - */ - public function createOrder($order) {...} +This package provides the `SettingsValidator` which uses the configuration type `Validation` to resolve the validators +that should be applied to the value. It distinguishes between validators that are applied to the value itself and its +properties. -Then your Validation.yaml could look like this: +## Resolving the validation configuration - Vendor\Package\Domain\Model\Order: - # validates the complete object - self: - 'Vendor.Package:SomeOtherValidator': [] - # validates properties of the object - properties: - price: - NumberRange: - maximum: 20 - minimum: 10 - customer: - 'DigiComp.SettingValidator:Settings': - name: 'OrderCustomer' +The `SettingsValidator` has an option `name`. If it is set, the name is used to resolve the validation configuration, +otherwise the type of the value is used, which is mainly useful for objects where the FQCN is used. - OrderCustomer: - properties: - firstName: - StringLength: - minimum: 3 - maximum: 20 +### Resolving by option `name` -As you see: Nesting is possible ;) That way you can easily construct flexible structures. +To resolve the validation configuration by name just use the option `name`. -The SettingsValidator has an optional option: "name" - If you don't give one, it assumes your validation value is an -object and searches in Validation.yaml for the FQCN. +```php +/** + * @Flow\Validate(type="DigiComp.SettingValidator:Settings", options={"name"="MyNamedValidator"}) + * @var MyObject + */ +protected MyObject $myObject; +``` + +The `SettingsValidator` will search for an entry inside the `Validation.yaml` with that name. + +```yaml +MyNamedValidator: + ... +``` + +### Resolving by type + +To resolve the validation configuration by type just do not set the option `name`. + +```php +/** + * @Flow\Validate(type="DigiComp.SettingValidator:Settings") + * @var MyObject + */ +protected MyObject $myObject; +``` + +The `SettingsValidator` will search for an entry inside the `Validation.yaml` with the FQCN of `MyObject`. + +```yaml +My\Package\Domain\Model\MyObject: + ... +``` + +## The validation configuration + +### Difference between `self` and `properties` + +`self` contains a map of validators that are applied to the value itself. `properties` contains a map with property +names of the value you would like to validate and each entry contains a map of validators that are applied to that +property. + +```yaml +MyNamedValidator: + self: + ... + properties: + myProperty1: + ... + myProperty2: + ... +``` + +### Configuring a validator + +To configure a validator you use the type of the validator as key and the options as entries of that key. If the +validator has no options or all the default values are used, set an empty map as options. + +```yaml +MyNamedValidator: + self: + 'My.Package:SomeValidator': + myOption: "myOptionValue" + properties: + myProperty1: + 'My.Package:SomeOtherValidator': {} + myProperty2: + 'My.Package:SomeOtherValidator': {} +``` + +### Disable a validator + +To disable a validator you need to set the options to `null`. + +```yaml +MyNamedValidator: + self: + 'My.Package:SomeValidator': ~ +``` + +## Using the `SettingsValidator` + +The `SettingsValidator` can be used to reduce the number of `@Flow\Validate` annotations and gives you the possibility +of overwriting existing validation configurations in other packages. + +### Using on properties + +Old PHP code: + +```php +/** + * @Flow\Validate(type="My.Package:SomeValidator", options={"myOption"="myOptionValue"}) + * @Flow\Validate(type="My.Package:SomeOtherValidator") + * @var MyObject + */ +protected MyObject $myObject; +``` + +New PHP code: + +```php +/** + * @Flow\Validate(type="DigiComp.SettingValidator:Settings", options={"name"="MyNamedValidator"}) + * @var MyObject + */ +protected MyObject $myObject; +``` + +New validation configuration: + +```yaml +MyNamedValidator: + self: + 'My.Package:SomeValidator': + myOption: "myOptionValue" + 'My.Package:SomeOtherValidator': {} +``` + +### Using on actions + +Old PHP code: + +```php +/** + * @Flow\Validate(argumentName="myObject", type="My.Package:SomeValidator", options={"myOption"="myOptionValue"}) + * @Flow\Validate(argumentName="myObject", type="My.Package:SomeOtherValidator") + * @param MyObject $myObject + */ +public function myAction(MyObject $myObject) +{ + ... +} +``` + +New PHP code: + +```php +/** + * @Flow\Validate(argumentName="myObject", type="DigiComp.SettingValidator:Settings", options={"name"="MyNamedValidator"}) + * @param MyObject $myObject + */ +public function myAction(MyObject $myObject) +{ + ... +} +``` + +New validation configuration: + +```yaml +MyNamedValidator: + self: + 'My.Package:SomeValidator': + myOption: "myOptionValue" + 'My.Package:SomeOtherValidator': {} +``` + +### Using inside validator configurations + +You can use the `SettingsValidator` inside the validator configuration to easily construct flexible structures. + +```yaml +MyNamedValidator: + properties: + myProperty1: + 'DigiComp.SettingValidator:Settings': + name: "MyOtherNamedValidator" + +MyOtherNamedValidator: + self: + 'My.Package:SomeOtherValidator': {} +``` + +## Providing an empty validator + +It can be useful to provide an empty validator in code that is used by many projects. By doing so you can make sure that +a different validation is possible in any project. + +```php +/** + * @Flow\Validate(argumentName="myObject", type="DigiComp.SettingValidator:Settings", options={"name"="MyNamedValidator"}) + * @param MyObject $myObject + */ +public function myAction(MyObject $myObject) +{ + ... +} +``` + +```yaml +MyNamedValidator: {} +``` diff --git a/Resources/Private/Schema/Validation.schema.yaml b/Resources/Private/Schema/Validation.schema.yaml index c1dad01..71bc462 100644 --- a/Resources/Private/Schema/Validation.schema.yaml +++ b/Resources/Private/Schema/Validation.schema.yaml @@ -1,11 +1,11 @@ -type: 'dictionary' +type: "dictionary" additionalProperties: - type: 'dictionary' + type: "dictionary" additionalProperties: false properties: - type: 'dictionary' + type: "dictionary" additionalProperties: false properties: - type: 'dictionary' + type: "dictionary" self: - type: 'dictionary' + type: "dictionary" diff --git a/composer.json b/composer.json index bd79b28..d3f47f9 100644 --- a/composer.json +++ b/composer.json @@ -2,23 +2,8 @@ "name": "digicomp/settingvalidator", "description": "Just a Neos\\Flow Validator resolving other Validators with Configuration/Validation.yaml", "type": "neos-package", - "authors": [ - { - "name": "Ferdinand Kuhl", - "email": "f.kuhl@digital-competence.de", - "homepage": "http://www.digital-competence.de", - "role": "Developer" - } - ], - "license": "MIT", - "homepage": "https://github.com/fcool/DigiComp.SettingValidator", - "keywords": [ - "Neos", - "Flow", - "validation" - ], "require": { - "neos/flow": "^6.3", + "neos/flow": "^6.3.5", "php": "~7.4.0" }, "autoload": { @@ -36,8 +21,8 @@ "package-key": "DigiComp.SettingValidator" }, "branch-alias": { - "dev-develop": "3.1.x-dev", - "dev-version/1.x-dev": "1.1.x-dev" + "dev-develop": "3.0.x-dev", + "dev-version/1.x-dev": "1.0.x-dev" }, "applied-flow-migrations": [ "Inwebs.Basket-201409170938", @@ -75,5 +60,20 @@ "Neos.Flow-20190425144900", "Neos.Flow-20190515215000" ] - } + }, + "authors": [ + { + "name": "Ferdinand Kuhl", + "email": "f.kuhl@digital-competence.de", + "homepage": "http://www.digital-competence.de", + "role": "Developer" + } + ], + "license": "MIT", + "homepage": "https://github.com/fcool/DigiComp.SettingValidator", + "keywords": [ + "Neos", + "Flow", + "validation" + ] }