[BREAKING] Extbase validator interface changed (#522)

* [BREAKING] Extbase validator interface changed https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/12.0/Breaking-96998-ExtbaseValidatorInterfaceChanged.html refs TYPO3-Documentation/TYPO3CMS-Reference-CoreApi#1624 * [BREAKING] TYPO3 Frontend always rendered in UTF-8 https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/12.0/Breaking-97065-TYPO3FrontendAlwaysRenderedInUTF-8.html refs TYPO3-Documentation/TYPO3CMS-Reference-CoreApi#1624 Co-authored-by: lina.wolf <[email protected]>
TYPO3-Documentation · Apr 4, 2022 · 518e076 · 518e076
1 parent 8dc56dd
commit 518e076
Show file tree

Hide file tree

Showing 7 changed files with 70 additions and 102 deletions.
diff --git a/Documentation/4-FirstExtension/4-make-products-persistent.rst b/Documentation/4-FirstExtension/4-make-products-persistent.rst
@@ -53,7 +53,7 @@ The configuration is stored in a PHP array, the *table configuration array* (in
 
 .. seealso::
    You can find the full documentation for all *Table Configuration Array*
-   options in the :ref:`TCA Reference <t3tca:start>`
+   options in the :doc:`TCA Reference <t3tca:Index>`
 
 Create your configuration in the file:
 :file:`EXT:store_inventory/Configuration/TCA/tx_storeinventory_domain_model_product.php`.

diff --git a/Documentation/6-Persistence/2-configure-the-backends-inputforms.rst b/Documentation/6-Persistence/2-configure-the-backends-inputforms.rst
@@ -24,7 +24,7 @@ file :file:`Configuration/TCA/tx_sjroffers_domain_model_organization.php`.
    The configuration options that can be set in the TCA are very extensive and
    a broad description of them would cause the book to burst at its
    seams. However, each and every option is well documented in the
-   Online-documentation :ref:`TCA Reference <t3tca:start>`
+   Online-documentation :doc:`TCA Reference <t3tca:Index>`
 
 First, you should dip into the top layer of the TCA hierarchy. The TCA
 for table *tx_sjroffers_domain_model_organization* is in the

diff --git a/Documentation/9-CrosscuttingConcerns/2-validating-domain-objects.rst b/Documentation/9-CrosscuttingConcerns/2-validating-domain-objects.rst
@@ -37,32 +37,12 @@ Validators for checking of invariants
 
 A validator is a PHP class that has to check a certain invariant. All
 validators that are used in Extbase extensions have to implement the interface
-:php:`ValidatorInterface`:
+:php:`ValidatorInterface`. In most use cases it is recommended to extend the
+:php:`TYPO3\CMS\Extbase\Validation\Validator\AbstractValidator`, overriding
+the abstract method :php:`isValid()`.
 
-.. include:: /CodeSnippets/StyleguideCode/ValidatorInterface.rst.txt
-
-This interface requires validators to implement two methods:
-
-- :php:`validate($value)`
-- :php:`getOptions()`
-
-The main method is :php:`validate()`, which is called by the framework.
-The value to be validated is passed to the :php:validate() method where it's validity is checked.
-
-.. note::
-
-    The example below never returns anything but is using $this->addError() instead.
-    No return-values are given for validate()
-    although the interface states, that the method `validate` should return
-    a :php:`\TYPO3\CMS\Extbase\Error\Result` object. 
-    Most people who create custom validators extend the class
-    :php:`\TYPO3\CMS\Extbase\Validation\Validator\AbstractValidator`.
-    Instead the bool method isValid is called.
-    This enables you to call the addError()` or `$this->addError($error, 1624260704)` 
-    method and let the abstract
-    validator method `validate` take care of returning a proper result object 
-    of type `\TYPO3\CMS\Extbase\Error\Result` to the validation
-    framework. 
+The method :php:`isValid()` does not return a value but adds an error to the
+:php:`TYPO3\CMS\Extbase\Error\Result` in case the validation fails.
 
 There are 2 types of validation checks:
 #.  A loose check is making only a relaxed check over a very large range of possible values.
@@ -77,23 +57,30 @@ value.
 For example, a validator that checks whether the passed string is
 a valid email address, looks like this:
 
-::
+.. code-block:: php
+   :caption: EXT:my_extension/Classes/Domain/Validator/MyValidator.php
 
-    public function validate($value)
-    {
-        if (!is_string($value) || !$this->validEmail($value)) {
-            $this->addError(
-                $this->translateErrorMessage(
-                    'validator.emailaddress.notvalid',
-                    'extbase'
-                ), 1221559976);
-        }
-    }
+   use TYPO3\CMS\Extbase\Validation\Validator\AbstractValidator;
 
-    protected function validEmail($emailAddress)
-    {
-        return \TYPO3\CMS\Core\Utility\GeneralUtility::validEmail($emailAddress);
-    }
+   final class MyValidator extends AbstractValidator
+   {
+
+       public function isValid(mixed $value): void
+       {
+           if (!is_string($value) || !$this->validEmail($value)) {
+               $this->addError(
+                   $this->translateErrorMessage(
+                       'validator.emailaddress.notvalid',
+                       'extbase'
+                   ), 1221559976);
+           }
+       }
+
+       private function validEmail($emailAddress)
+       {
+           return \TYPO3\CMS\Core\Utility\GeneralUtility::validEmail($emailAddress);
+       }
+   }
 
 If ``$value`` is neither a string nor a valid email address, the validator
 adds an error by calling `$this->addError()`.
@@ -243,7 +230,7 @@ When you have created your own validator to check the invariants
 you can use it in the ``@TYPO3\CMS\Extbase\Annotation\Validate`` annotation using the full
 class name.
 
-Example: 
+Example:
 
 .. code-block:: php
    :caption: blog_example/Class/Domain/Model/Post.php
@@ -386,7 +373,7 @@ for example:
 
 .. code-block:: php
    :caption: extbase_example/Class/Controller/UserController.php
-   
+
    <?php
    declare(strict_types=1);
 
@@ -409,7 +396,7 @@ for example:
    }
 
 Now there are two possibilities how validators can be
-registered for domain objects: 
+registered for domain objects:
 
 *  directly in the model via ``@TYPO3\CMS\Extbase\Annotation\Validate`` annotation for single properties
 *  with an own validator class for complete domain objects.

diff --git a/Documentation/CodeSnippets/PhpDomain/ValidatorInterface.rst.txt b/Documentation/CodeSnippets/PhpDomain/ValidatorInterface.rst.txt
@@ -0,0 +1,27 @@
+.. Generated by https://github.com/linawolf/t3docs_restructured_api_tools 
+.. php:namespace::  TYPO3\CMS\Extbase\Validation\Validator
+
+.. php:interface:: ValidatorInterface
+
+   Contract for a validator
+
+   .. php:method:: validate(mixed value)
+   
+      Checks if the given value is valid according to the validator, and returns
+      the Error Messages object which occurred.
+
+      :param mixed $value: the value
+      :returntype: TYPO3\\CMS\\Extbase\\Error\\Result
+
+   .. php:method:: setOptions(array options)
+   
+      Receive validator options from framework.
+
+      :param array $options: the options
+
+   .. php:method:: getOptions()
+   
+      Returns the options of this validator which can be specified by setOptions().
+
+      :returntype: array
+
diff --git a/Documentation/CodeSnippets/StyleguideCode/ValidatorInterface.rst.txt b/Documentation/CodeSnippets/StyleguideCode/ValidatorInterface.rst.txt
diff --git a/Documentation/b-ExtbaseReference/Index.rst b/Documentation/b-ExtbaseReference/Index.rst
@@ -915,19 +915,19 @@ Since 1.1 (TYPO3 4.3), `$propertyName` is not necessarily only a simple property
    Two conditions are joined with a logical *and* that returns a condition.
    Multiple parameters are allowed, at least 2. As of TYPO3 version 12, passing the
    parameters as an array is not allowed. Use the following migration::
-   
+
        $constraints = [];
-       
+
        if (...) {
           $constraints[] = $query->equals('propertyName1', 'value1');
        }
-       
+
        if (...) {
           $constraints[] = $query->equals('propertyName2', 'value2');
        }
-       
+
        $query = $this->createQuery();
-       
+
        $numberOfConstraints = count($constraints);
        if ($numberOfConstraints === 1) {
            $query->matching(reset($constraints));
@@ -971,13 +971,11 @@ provides validators for common data types, but you can also write your own valid
 Validator implements the :php:`\TYPO3\CMS\Extbase\Validation\Validator\ValidatorInterface`
 that defines the following methods:
 
-`validate($value)`
-    Checks whether the object that was passed to the validator is valid. If not,
-    a :php:`\TYPO3\CMS\Extbase\Validation\Error` object should be returned.
+.. include:: /CodeSnippets/PhpDomain/ValidatorInterface.rst.txt
 
-`getOptions()`
-    Enables you to define validator options. These options apply to any further call
-    of the method validate().
+In most use cases extending the abstract class
+:php:`\TYPO3\CMS\Extbase\Validation\Validator\AbstractValidator` is sufficient
+however.
 
 You can call Validators in your own code with the method `createValidator($validatorName,
 $validatorOptions)` in :php:`\TYPO3\CMS\Extbase\Validation\ValidatorResolver`. Though in

diff --git a/Documentation/screenshots.json b/Documentation/screenshots.json
@@ -3,7 +3,7 @@
         "Core": {
             "screenshots": {
                 "codeSnippets": [
-                    {"action": "setCodeSnippetsTargetPath", "path": "CodeSnippets/StyleguideCode"},
+                    {"action": "setCodeSnippetsTargetPath", "path": "CodeSnippets/PhpDomain"},
                     {
                         "action": "createCodeSnippet",
                         "caption": "\\TYPO3\\CMS\\Extbase\\Validation\\Validator\\ValidatorInterface",
@@ -14,4 +14,4 @@
             }
         }
     }
-}
+}