Merge branch 'develop'

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"

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
+This package allows configuring validators with a new configuration type.
-Yaml-File in your Configuration directory.
 
-Let's imagine you had this action-method:
+## Introduction
 
-    /**
+This package provides the `SettingsValidator` which uses the configuration type `Validation` to resolve the validators
-     * @Flow\Validate(argumentName="order", type="DigiComp.SettingValidator:Settings")
+that should be applied to the value. It distinguishes between validators that are applied to the value itself and its
-     * @param Order $order
+properties.
+
+## Resolving the validation configuration
+
+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.
+
+### Resolving by option `name`
+
+To resolve the validation configuration by name just use the option `name`.
+
+```php
+/**
+ * @Flow\Validate(type="DigiComp.SettingValidator:Settings", options={"name"="MyNamedValidator"})
+ * @var MyObject
  */
-    public function createOrder($order) {...}
+protected MyObject $myObject;
+```
 
-Then your Validation.yaml could look like this:
+The `SettingsValidator` will search for an entry inside the `Validation.yaml` with that name.
 
-    Vendor\Package\Domain\Model\Order:
+```yaml
-      # validates the complete object
+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:
-        'Vendor.Package:SomeOtherValidator': []
+    ...
-      # validates properties of the object
   properties:
-        price:
+    myProperty1:
-          NumberRange:
+      ...
-            maximum: 20
+    myProperty2:
-            minimum: 10
+      ...
-        customer:
+```
+
+### 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: 'OrderCustomer'
+        name: "MyOtherNamedValidator"
 
-    OrderCustomer:
+MyOtherNamedValidator:
-      properties:
+  self:
-        firstName:
+    'My.Package:SomeOtherValidator': {}
-          StringLength:
+```
-            minimum: 3
-            maximum: 20
 
-As you see: Nesting is possible ;) That way you can easily construct flexible structures.
+## Providing an empty validator
 
-The SettingsValidator has an optional option: "name" - If you don't give one, it assumes your validation value is an
+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
-object and searches in Validation.yaml for the FQCN.
+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: {}
+```

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"

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-develop": "3.0.x-dev",
-            "dev-version/1.x-dev": "1.1.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"
+    ]
 }