docs: config file - provide better examples (#7396)

.php-cs-fixer.dist.php

@@ -22,15 +22,14 @@
     with this source code in the file LICENSE.
     EOF;
 
-$finder = PhpCsFixer\Finder::create()
+$finder = (new PhpCsFixer\Finder())
     ->ignoreDotFiles(false)
     ->ignoreVCSIgnored(true)
     ->exclude(['dev-tools/phpstan', 'tests/Fixtures'])
     ->in(__DIR__)
 ;
 
-$config = new PhpCsFixer\Config();
-$config
+return (new PhpCsFixer\Config())
     ->setRiskyAllowed(true)
     ->setRules([
         '@PHP74Migration' => true,
@@ -45,5 +44,3 @@
     ])
     ->setFinder($finder)
 ;
-
-return $config;

doc/config.rst

@@ -2,72 +2,142 @@
 Config file
 ===========
 
-Instead of using command line options to customize rules and rule sets, you can save the
-project configuration in a ``.php-cs-fixer.dist.php`` file in the root directory of your project.
+No config
+---------
+
+It is possible to *not* have the config file. In that case, the default rule set (@PSR12) will be applied, yet the path will need to be provided via CLI.
+
+.. code-block:: console
+
+    php php-cs-fixer.phar fix .
+
+It is also possible to provide command line options to customize rules, yet instead of using them,
+it's recommended to save the project configuration in a ``.php-cs-fixer.dist.php`` file in the root directory of your project.
 The file must return an instance of `PhpCsFixer\\ConfigInterface <../src/ConfigInterface.php>`_
 which lets you configure the rules, the files and directories that
 need to be analyzed. You may also create ``.php-cs-fixer.php`` file, which is
 the local configuration that will be used instead of the project configuration. It
 is a good practice to add that file into your ``.gitignore`` file.
-With the ``--config`` option you can specify the path to the
-``.php-cs-fixer.php`` file.
+With the ``--config`` option you can specify the path to the config file.
 
-The example below will add two rules to the default list of PSR12 set rules:
+
+The simplest config
+-------------------
+
+The simplest config declares paths under control and rules to apply/check:
 
 .. code-block:: php
 
     <?php
 
-    $finder = PhpCsFixer\Finder::create()
-        ->exclude('somedir')
-        ->notPath('src/Symfony/Component/Translation/Tests/fixtures/resources.php')
+    $finder = (new PhpCsFixer\Finder())
         ->in(__DIR__)
     ;
 
-    $config = new PhpCsFixer\Config();
-    return $config->setRules([
-            '@PSR12' => true,
-            'strict_param' => true,
-            'array_syntax' => ['syntax' => 'short'],
+    return (new PhpCsFixer\Config())
+        ->setRules([
+            '@PER-CS' => true,
+            '@PHP82Migration' => true,
+        ])
+        ->setFinder($finder)
+    ;
+
+Default finder ignores ``__DIR__ . "/vendor"`` dir, "hidden" paths (ones starting with a dot) and VCS paths (e.g. ``.git``), and filter only for ``*.php`` files.
+
+Configuring paths
+-----------------
+
+The example below will manipulate which paths to fix or not:
+
+.. code-block:: php
+
+    <?php
+
+    $finder = (new PhpCsFixer\Finder())
+        ->in(__DIR__)
+        ->exclude([
+            'autogenerated_content',
+            'tests/fixtures',
+        ])
+        ->notPath([
+            'dump.php',
+            'src/exception_file.php',
+        ])
+    ;
+
+    return (new PhpCsFixer\Config())
+        ->setRules([
+            '@PhpCsFixer' => true,
         ])
         ->setFinder($finder)
     ;
 
-**NOTE**: ``exclude`` will work only for directories, so if you need to exclude file, try ``notPath``.
-Both ``exclude`` and ``notPath`` methods accept only relative paths to the ones defined with the ``in`` method.
+Note that ``exclude`` will work only for directories, so if you need to exclude a file, use ``notPath``.
+Both ``exclude`` and ``notPath`` methods accept only relative paths to the ones defined with the ``in`` method, can be called multiple times and accept string or array of them.
 
 See `Symfony\\Finder <https://symfony.com/doc/current/components/finder.html#location>`_
 online documentation for other `Finder` methods.
 
+Configuring rules
+-----------------
+
+The example below will add two rules to the default list of PSR12 set rules:
+
+.. code-block:: php
+
+    <?php
+
+    $finder = (new PhpCsFixer\Finder())
+        ->in(__DIR__)
+    ;
+
+    return (new PhpCsFixer\Config())
+        ->setRules([
+            '@PSR12' => true,
+            'strict_param' => true,
+            'array_syntax' => ['syntax' => 'short'],
+        ])
+        ->setFinder($finder)
+    ;
+
 You may also use an exclude list for the rules instead of the above shown include approach.
-The following example shows how to use all ``Symfony`` rules but the ``full_opening_tag`` rule.
+The following example shows how to use all ``PhpCsFixer`` rules but without the ``align_multiline_comment`` rule.
 
 .. code-block:: php
 
     <?php
 
-    $finder = PhpCsFixer\Finder::create()
+    $finder = (new PhpCsFixer\Finder())
         ->in(__DIR__)
-        ->exclude('somedir')
     ;
 
-    $config = new PhpCsFixer\Config();
-    return $config->setRules([
-            '@Symfony' => true,
-            'full_opening_tag' => false,
+    return (new PhpCsFixer\Config())
+        ->setRules([
+            '@PhpCsFixer' => true,
+            'comment_type' => false,
         ])
         ->setFinder($finder)
     ;
 
+Configuring whitespaces
+-----------------------
+
 You may want to use non-linux whitespaces in your project. Then you need to
 configure them in your config file.
 
 .. code-block:: php
 
     <?php
 
-    $config = new PhpCsFixer\Config();
-    return $config
+    $finder = (new PhpCsFixer\Finder())
+        ->in(__DIR__)
+    ;
+
+    return (new PhpCsFixer\Config())
+        ->setRules([
+            '@Symfony' => true,
+        ])
+        ->setFinder($finder)
         ->setIndent("\t")
         ->setLineEnding("\r\n")
     ;