1c8c3746031b03c3098fdf20043a6b31f6590ea5
[Packages/TYPO3.CMS.git] / typo3 / sysext / core / Documentation / Changelog / master / Deprecation-83167-ReplaceValidateWithTYPO3CMSExtbaseAnnotationValidate.rst
1 .. include:: ../../Includes.txt
2
3 ===================================================================================
4 Deprecation: #83167 - Replace @validate with @TYPO3\CMS\Extbase\Annotation\Validate
5 ===================================================================================
6
7 See :issue:`83167`
8
9 Description
10 ===========
11
12 The :php:`@validate` annotation has been marked as deprecated and should be replaced with the doctrine annotation
13 :php:`@TYPO3\CMS\Extbase\Annotation\Validate`.
14
15
16 Impact
17 ======
18
19 From version 9.3 on, :php:`@validate` has been marked as deprecated and will be removed in version 10.
20
21
22 Affected Installations
23 ======================
24
25 All extensions that use :php:`@validate`
26
27
28 Migration
29 =========
30
31 Use :php:`@TYPO3\CMS\Extbase\Annotation\Validate` instead.
32
33
34 Examples:
35 ---------
36
37 The following examples show both the old and the new way of using validation annotations. Both versions can still be used
38 in the same doc block, but you should start using the new way today.
39
40 .. code-block:: php
41
42         use TYPO3\CMS\Extbase\Annotation as Extbase;
43
44
45 .. note::
46
47    Doctrine annotations are actual classes, so they can be either used via FQCN, imported via the use statement or even
48    be aliased which is the preferred way. As doctrine annotations can only be used in the Extbase context (for now), the
49    aliased version makes that perfectly clear even for people that are new to TYPO3.
50
51 .. tip::
52
53    When using PhpStorm, you can install the `PHP Annotation` plugin that recognizes the annotation classes and makes you
54    jump directly into them. Also, it enables autocompletion for annotation options.
55
56 Validators for class properties
57 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58
59 This is how annotations look like, that register validators without options
60
61 .. code-block:: php
62
63         /**
64          * @validate NotEmpty
65          * @Extbase\Validate("NotEmpty")
66          * @var Foo
67          */
68         public $property;
69
70 .. code-block:: php
71
72         /**
73          * @validate NotEmpty
74          * @Extbase\Validate(validator="NotEmpty")
75          * @var Foo
76          */
77         public $property;
78
79 This is how annotations look like, that register validators with options
80
81 .. code-block:: php
82
83         /**
84          * @validate StringLength(minimum=3, maximum=50)
85          * @Extbase\Validate("StringLength", options={"minimum": 3, "maximum": 50})
86          * @var Foo
87          */
88         public $property;
89
90 .. important::
91
92    Registering multiple validators, separated by comma, is not possible any more. Instead, use one validator per line.
93
94 .. code-block:: php
95
96         /**
97          * @validate StringLength(minimum=3), StringLength(maximum=50)
98          * @Extbase\Validate("StringLength", options={"minimum": 3})
99          * @Extbase\Validate("StringLength", options={"maximum": 50})
100          * @var Foo
101          */
102         public $property;
103
104 Validators for method params
105 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
106
107 .. important::
108
109    When using validators for method params, you need to define what param the validator is registered for. Also, please
110    note that the param name does no longer include the dollar sign.
111
112 .. code-block:: php
113
114         /**
115          * @validate $bar NotEmpty
116          * @Extbase\Validate("NotEmpty", param="bar")
117          * @var string $foo
118          * @var string $bar
119          */
120         public function method(string $foo, string $bar)
121         {
122         }
123
124 Full qualified validator class names and aliases
125 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126
127 Of course it's still possible to reference validators by extension key, aliases and FQCN's.
128
129 .. code-block:: php
130
131         /**
132          * @Extbase\Validate("NotEmpty")
133          * @Extbase\Validate("TYPO3.CMS.Extbase:NotEmpty")
134          * @Extbase\Validate("TYPO3\CMS\Extbase\Validation\Validator\NotEmptyValidator")
135          * @Extbase\Validate("\TYPO3\CMS\Extbase\Validation\Validator\NotEmptyValidator")
136          */
137         protected $property;
138
139 .. index:: PHP-API, ext:extbase, FullyScanned