doc/rules/phpdoc/phpdoc_separation.rst
phpdoc_separationAnnotations in PHPDoc should be grouped together so that annotations of the same type immediately follow each other. Annotations of a different type are separated by a single blank line.
This rule is CONFIGURABLE
You can configure this rule using the following options: ``groups``,
``skip_unlisted_annotations``.
Configuration
-------------
``groups``
~~~~~~~~~~
Sets of annotation types to be grouped together. Use ``*`` to match any tag
character.
Allowed types: ``list<list<string>>``
Default value: ``[['author', 'copyright', 'license'], ['category', 'package', 'subpackage'], ['property', 'property-read', 'property-write'], ['deprecated', 'link', 'see', 'since']]``
``skip_unlisted_annotations``
Whether to skip annotations that are not listed in any group.
Allowed types: bool
Default value: false
Default value (future-mode): true
Example #1
*Default* configuration.
.. code-block:: diff
--- Original
+++ New
<?php
/**
* Hello there!
*
* @author John Doe
+ *
* @custom Test!
*
* @throws Exception|RuntimeException foo
+ *
* @param string $foo
+ * @param bool $bar Bar
*
- * @param bool $bar Bar
* @return int Return the number of changes.
*/
Example #2
With configuration: ['groups' => [['deprecated', 'link', 'see', 'since'], ['author', 'copyright', 'license'], ['category', 'package', 'subpackage'], ['property', 'property-read', 'property-write'], ['param', 'return']]].
.. code-block:: diff
--- Original +++ New <?php /** * Hello there! * * @author John Doe
Example #3
With configuration: ``['groups' => [['author', 'throws', 'custom'], ['return', 'param']]]``.
.. code-block:: diff
--- Original
+++ New
<?php
/**
* Hello there!
*
* @author John Doe
* @custom Test!
+ * @throws Exception|RuntimeException foo
*
- * @throws Exception|RuntimeException foo
* @param string $foo
- *
* @param bool $bar Bar
* @return int Return the number of changes.
*/
Example #4
With configuration: ['groups' => [['ORM\\*'], ['Assert\\*']]].
.. code-block:: diff
--- Original +++ New <?php /** * @ORM\Id
Example #5
With configuration: ``['skip_unlisted_annotations' => true]``.
.. code-block:: diff
--- Original
+++ New
<?php
/**
* Hello there!
*
* @author John Doe
+ *
* @custom Test!
*
* @throws Exception|RuntimeException foo
* @param string $foo
- *
* @param bool $bar Bar
* @return int Return the number of changes.
*/
Rule sets
---------
The rule is part of the following rule sets:
- `@PhpCsFixer <./../../ruleSets/PhpCsFixer.rst>`_ with config:
``['groups' => [['Annotation', 'NamedArgumentConstructor', 'Target'], ['author', 'copyright', 'license'], ['category', 'package', 'subpackage'], ['property', 'property-read', 'property-write'], ['deprecated', 'link', 'see', 'since']], 'skip_unlisted_annotations' => false]``
- `@Symfony <./../../ruleSets/Symfony.rst>`_ with config:
``['groups' => [['Annotation', 'NamedArgumentConstructor', 'Target'], ['author', 'copyright', 'license'], ['category', 'package', 'subpackage'], ['property', 'property-read', 'property-write'], ['deprecated', 'link', 'see', 'since']], 'skip_unlisted_annotations' => false]``
References
----------
- Fixer class: `PhpCsFixer\\Fixer\\Phpdoc\\PhpdocSeparationFixer <./../../../src/Fixer/Phpdoc/PhpdocSeparationFixer.php>`_
- Test class: `PhpCsFixer\\Tests\\Fixer\\Phpdoc\\PhpdocSeparationFixerTest <./../../../tests/Fixer/Phpdoc/PhpdocSeparationFixerTest.php>`_
The test class defines officially supported behaviour. Each test case is a part of our backward compatibility promise.