PHP-CS-Fixer/doc/config.rst

===========
Config file
===========

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 config file.


The simplest config
-------------------

The simplest config declares paths under control and rules to apply/check:

.. code-block:: php

    <?php

    $finder = (new PhpCsFixer\Finder())
        ->in(__DIR__)
    ;

    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 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 ``PhpCsFixer`` rules but without the ``align_multiline_comment`` rule.

.. code-block:: php

    <?php

    $finder = (new PhpCsFixer\Finder())
        ->in(__DIR__)
    ;

    return (new PhpCsFixer\Config())
        ->setRules([
            '@PhpCsFixer' => true,
            'align_multiline_comment' => 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

    $finder = (new PhpCsFixer\Finder())
        ->in(__DIR__)
    ;

    return (new PhpCsFixer\Config())
        ->setRules([
            '@Symfony' => true,
        ])
        ->setFinder($finder)
        ->setIndent("\t")
        ->setLineEnding("\r\n")
    ;