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

No config
---------

It is possible to *not* have the config file. In that case, the default rule set (``@PSR12`` for v3, ``@auto`` for v4) will be applied,
and under v3, the path will need to be provided via CLI (defaults to ``.`` under v4).

.. code-block:: console

    php php-cs-fixer.phar fix .

While it is possible to provide command line options to configure rules,
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, finder (the files and directories that
need to be analysed), select output format and even configure path to ``PHP``.

You may also create ``.php-cs-fixer.php`` file, which is
the local configuration that will be used instead of the project configuration.
You can use it to customise for your environment (like path to ``PHP``) or preference (like output format or progress indicator),
while ruleset / finder shall be re-imported from 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, when it is named differently.


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,
            '@PHP8x2Migration' => 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)
    ;

If you need to set up exception for rules, eg ignore or reconfigure a rule for specific files, check the `Rules exceptions <./rules_exceptions.rst>`_.


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")
    ;

It's possible to register custom rule sets, which makes it easier to reuse custom configuration between multiple projects. If you have prepared rule set, you can register it, and then enable it in the rules. Custom rule sets (in this example ``\MyNameSpace\MyRuleSetClass``) must implement ``\PhpCsFixer\RuleSet\RuleSetDefinitionInterface``.

.. code-block:: php

    <?php

    return (new PhpCsFixer\Config())
        ->registerCustomRuleSets([
            MyNameSpace\MyRuleSetClass::class, // It identifies itself as '@MyRuleSet'
        ])
        ->setRules([
            '@MyRuleSet' => true,
        ])
    ;

ℹ️ If you use ``\PhpCsFixer\ConfigInterface`` implementation other than built-in one, make sure it implements ``\PhpCsFixer\CustomRulesetsAwareConfigInterface``.