minor: Unify "blank lines before namespace" fixers (#7053)

doc/list.rst

@@ -84,6 +84,25 @@ List of Available Rules
    Part of rule sets `@PhpCsFixer <./ruleSets/PhpCsFixer.rst>`_ `@Symfony <./ruleSets/Symfony.rst>`_
 
    `Source PhpCsFixer\\Fixer\\Operator\\BinaryOperatorSpacesFixer <./../src/Fixer/Operator/BinaryOperatorSpacesFixer.php>`_
+-  `blank_lines_before_namespace <./rules/namespace_notation/blank_lines_before_namespace.rst>`_
+
+   Controls blank lines before a namespace declaration.
+
+   Configuration options:
+
+   - | ``min_line_breaks``
+     | Minimum line breaks that should exist before namespace declaration.
+     | Allowed types: ``int``
+     | Default value: ``2``
+   - | ``max_line_breaks``
+     | Maximum line breaks that should exist before namespace declaration.
+     | Allowed types: ``int``
+     | Default value: ``2``
+
+
+   Part of rule sets `@PER <./ruleSets/PER.rst>`_ `@PER-CS1.0 <./ruleSets/PER-CS1.0.rst>`_ `@PSR12 <./ruleSets/PSR12.rst>`_ `@PhpCsFixer <./ruleSets/PhpCsFixer.rst>`_ `@Symfony <./ruleSets/Symfony.rst>`_
+
+   `Source PhpCsFixer\\Fixer\\NamespaceNotation\\BlankLinesBeforeNamespaceFixer <./../src/Fixer/NamespaceNotation/BlankLinesBeforeNamespaceFixer.php>`_
 -  `blank_line_after_namespace <./rules/namespace_notation/blank_line_after_namespace.rst>`_
 
    There MUST be one blank line after the namespace declaration.
@@ -1417,6 +1436,8 @@ List of Available Rules
 
    There should be no blank lines before a namespace declaration.
 
+   *warning deprecated*   Use ``blank_lines_before_namespace`` instead.
+
    `Source PhpCsFixer\\Fixer\\NamespaceNotation\\NoBlankLinesBeforeNamespaceFixer <./../src/Fixer/NamespaceNotation/NoBlankLinesBeforeNamespaceFixer.php>`_
 -  `no_break_comment <./rules/control_structure/no_break_comment.rst>`_
 
@@ -2844,7 +2865,7 @@ List of Available Rules
 
    There should be exactly one blank line before a namespace declaration.
 
-   Part of rule sets `@PER <./ruleSets/PER.rst>`_ `@PER-CS1.0 <./ruleSets/PER-CS1.0.rst>`_ `@PSR12 <./ruleSets/PSR12.rst>`_ `@PhpCsFixer <./ruleSets/PhpCsFixer.rst>`_ `@Symfony <./ruleSets/Symfony.rst>`_
+   *warning deprecated*   Use ``blank_lines_before_namespace`` instead.
 
    `Source PhpCsFixer\\Fixer\\NamespaceNotation\\SingleBlankLineBeforeNamespaceFixer <./../src/Fixer/NamespaceNotation/SingleBlankLineBeforeNamespaceFixer.php>`_
 -  `single_class_element_per_statement <./rules/class_notation/single_class_element_per_statement.rst>`_

doc/ruleSets/PSR12.rst

@@ -10,6 +10,7 @@ Rules
 - `@PSR2 <./PSR2.rst>`_
 - `blank_line_after_opening_tag <./../rules/php_tag/blank_line_after_opening_tag.rst>`_
 - `blank_line_between_import_groups <./../rules/whitespace/blank_line_between_import_groups.rst>`_
+- `blank_lines_before_namespace <./../rules/namespace_notation/blank_lines_before_namespace.rst>`_
 - `class_definition <./../rules/class_notation/class_definition.rst>`_
   config:
   ``['inline_constructor_arguments' => false, 'space_before_parenthesis' => true]``
@@ -32,7 +33,6 @@ Rules
   ``['imports_order' => ['class', 'function', 'const'], 'sort_algorithm' => 'none']``
 - `return_type_declaration <./../rules/function_notation/return_type_declaration.rst>`_
 - `short_scalar_cast <./../rules/cast_notation/short_scalar_cast.rst>`_
-- `single_blank_line_before_namespace <./../rules/namespace_notation/single_blank_line_before_namespace.rst>`_
 - `single_import_per_statement <./../rules/import/single_import_per_statement.rst>`_
   config:
   ``['group_to_single_imports' => false]``

doc/rules/index.rst

@@ -491,16 +491,19 @@ Namespace Notation
 - `blank_line_after_namespace <./namespace_notation/blank_line_after_namespace.rst>`_
 
   There MUST be one blank line after the namespace declaration.
+- `blank_lines_before_namespace <./namespace_notation/blank_lines_before_namespace.rst>`_
+
+  Controls blank lines before a namespace declaration.
 - `clean_namespace <./namespace_notation/clean_namespace.rst>`_
 
   Namespace must not contain spacing, comments or PHPDoc.
-- `no_blank_lines_before_namespace <./namespace_notation/no_blank_lines_before_namespace.rst>`_
+- `no_blank_lines_before_namespace <./namespace_notation/no_blank_lines_before_namespace.rst>`_ *(deprecated)*
 
   There should be no blank lines before a namespace declaration.
 - `no_leading_namespace_whitespace <./namespace_notation/no_leading_namespace_whitespace.rst>`_
 
   The namespace declaration line shouldn't contain leading whitespace.
-- `single_blank_line_before_namespace <./namespace_notation/single_blank_line_before_namespace.rst>`_
+- `single_blank_line_before_namespace <./namespace_notation/single_blank_line_before_namespace.rst>`_ *(deprecated)*
 
   There should be exactly one blank line before a namespace declaration.
 

doc/rules/namespace_notation/blank_lines_before_namespace.rst

@@ -0,0 +1,122 @@
+=====================================
+Rule ``blank_lines_before_namespace``
+=====================================
+
+Controls blank lines before a namespace declaration.
+
+Configuration
+-------------
+
+``min_line_breaks``
+~~~~~~~~~~~~~~~~~~~
+
+Minimum line breaks that should exist before namespace declaration.
+
+Allowed types: ``int``
+
+Default value: ``2``
+
+``max_line_breaks``
+~~~~~~~~~~~~~~~~~~~
+
+Maximum line breaks that should exist before namespace declaration.
+
+Allowed types: ``int``
+
+Default value: ``2``
+
+Examples
+--------
+
+Example #1
+~~~~~~~~~~
+
+*Default* configuration.
+
+.. code-block:: diff
+
+   --- Original
+   +++ New
+   -<?php  namespace A {}
+   +<?php
+   +
+   +namespace A {}
+
+Example #2
+~~~~~~~~~~
+
+With configuration: ``['min_line_breaks' => 1]``.
+
+.. code-block:: diff
+
+   --- Original
+   +++ New
+   -<?php  namespace A {}
+   +<?php
+   +namespace A {}
+
+Example #3
+~~~~~~~~~~
+
+With configuration: ``['max_line_breaks' => 2]``.
+
+.. code-block:: diff
+
+   --- Original
+   +++ New
+    <?php
+
+    declare(strict_types=1);
+
+   -
+   -
+    namespace A{}
+
+Example #4
+~~~~~~~~~~
+
+With configuration: ``['min_line_breaks' => 2]``.
+
+.. code-block:: diff
+
+   --- Original
+   +++ New
+    <?php
+
+    /** Some comment */
+   +
+    namespace A{}
+
+Example #5
+~~~~~~~~~~
+
+With configuration: ``['min_line_breaks' => 0, 'max_line_breaks' => 0]``.
+
+.. code-block:: diff
+
+   --- Original
+   +++ New
+   -<?php
+   -
+   -namespace A{}
+   +<?php namespace A{}
+
+Rule sets
+---------
+
+The rule is part of the following rule sets:
+
+@PER
+  Using the `@PER <./../../ruleSets/PER.rst>`_ rule set will enable the ``blank_lines_before_namespace`` rule with the default config.
+
+@PER-CS1.0
+  Using the `@PER-CS1.0 <./../../ruleSets/PER-CS1.0.rst>`_ rule set will enable the ``blank_lines_before_namespace`` rule with the default config.
+
+@PSR12
+  Using the `@PSR12 <./../../ruleSets/PSR12.rst>`_ rule set will enable the ``blank_lines_before_namespace`` rule with the default config.
+
+@PhpCsFixer
+  Using the `@PhpCsFixer <./../../ruleSets/PhpCsFixer.rst>`_ rule set will enable the ``blank_lines_before_namespace`` rule with the default config.
+
+@Symfony
+  Using the `@Symfony <./../../ruleSets/Symfony.rst>`_ rule set will enable the ``blank_lines_before_namespace`` rule with the default config.

doc/rules/namespace_notation/no_blank_lines_before_namespace.rst

@@ -4,6 +4,14 @@ Rule ``no_blank_lines_before_namespace``
 
 There should be no blank lines before a namespace declaration.
 
+Warning
+-------
+
+This rule is deprecated and will be removed on next major version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You should use ``blank_lines_before_namespace`` instead.
+
 Examples
 --------
 

doc/rules/namespace_notation/single_blank_line_before_namespace.rst

@@ -4,6 +4,14 @@ Rule ``single_blank_line_before_namespace``
 
 There should be exactly one blank line before a namespace declaration.
 
+Warning
+-------
+
+This rule is deprecated and will be removed on next major version
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You should use ``blank_lines_before_namespace`` instead.
+
 Examples
 --------
 
@@ -30,23 +38,3 @@ Example #2
 
    -
     namespace A{}
-
-Rule sets
----------
-
-The rule is part of the following rule sets:
-
-@PER
-  Using the `@PER <./../../ruleSets/PER.rst>`_ rule set will enable the ``single_blank_line_before_namespace`` rule.
-
-@PER-CS1.0
-  Using the `@PER-CS1.0 <./../../ruleSets/PER-CS1.0.rst>`_ rule set will enable the ``single_blank_line_before_namespace`` rule.
-
-@PSR12
-  Using the `@PSR12 <./../../ruleSets/PSR12.rst>`_ rule set will enable the ``single_blank_line_before_namespace`` rule.
-
-@PhpCsFixer
-  Using the `@PhpCsFixer <./../../ruleSets/PhpCsFixer.rst>`_ rule set will enable the ``single_blank_line_before_namespace`` rule.
-
-@Symfony
-  Using the `@Symfony <./../../ruleSets/Symfony.rst>`_ rule set will enable the ``single_blank_line_before_namespace`` rule.