automated-typo3-update/Documentation/source/extending.rst

.. _extending:

Extending
=========

It's possible to extend the provided migrations.

Also adding tests is pretty easy and done by adding a folder with an input file and an file
holding the expectations.

.. _extending-sniffs:

Sniffs
------

Follow the official docs of `phpcs`_:
https://github.com/squizlabs/PHP_CodeSniffer/wiki/Coding-Standard-Tutorial#user-content-creating-the-sniff

The following resources might be helpful during working with ``phpcs``:

- https://secure.php.net/manual/en/tokens.php

- :file:`CodeSniffer/Tokens.php`

- :file:`CodeSniffer/File.php`

.. _extending-features:

Features
--------

Sniffs do not always add errors or warnings in our standard, instead for more flexibility, we use
them to find specific "tokens", e.g. class names. We then attach so called *Features* to sniffs to
work on that token.

E.g. we deliver the Feature ``LegacyClassnameFeature`` which will check whether a given class name
is legacy and should be replaced. As class names may occur in many places like type hints or php doc
blocks, the sniffs will detect the class names and the feature will work on them.

Features can be attached to the sniffs. A feature has to implement the ``FeatureInterface`` and will
work on tokens found by sniffs.

To attach a Feature to Sniffs, provide a yaml-configuration, see :ref:`configuration-features`.

.. _extending-tests:

Tests
-----

We are using `phpunit` as testing framework.

Adding tests for sniffs is as easy as providing the same folder structure as for the sniff, just
inside the :file:`tests/Fixtures` folder. Instead of adding the sniff as a file, you have to provide
a folder named like the sniff. E.g. you want to add a test for sniff
:file:`src/Standards/Typo3Update/Sniffs/LegacyClassnames/DocCommentSniff.php`, the following folder
has to exist: :file:`tests/Fixtures/Standards/Typo3Update/Sniffs/LegacyClassnames/DocCommentSniff/`.

.. _extending-tests-single:

Single test per sniff
^^^^^^^^^^^^^^^^^^^^^

Inside of the folder at least a file :file:`InputFileForIssues.php` has to exist, containing PHP
code to use for the test. Also a file :file:`Expected.json` has to exist, with the json result of
calling ``phpcs`` with :file:`InputFileForIssues.php`.

Everything else is done out of the box.

If your sniff also implements fixable errors or warnings, you can further provide a
:file:`Expected.diff` which is generated by ``phpcbf``.

.. _extending-tests-multiple:

Multiple tests per sniff
^^^^^^^^^^^^^^^^^^^^^^^^

Also it's possible to provide multiple tests for a single sniff, e.g. with different cli arguments
like options for the sniff. In that case you have to place a :file:`Arguments.php` in the folder.
This file returns an array:

.. code-block:: php

    <?php

    return [
        'defaultVendor' => [],
        'customVendor' => [
            'runtime-set' => [
                'vendor' => 'MyCustomVendor',
            ],
        ],
    ];

In the example above ``defaultVendor`` and ``customVendor`` are subfolders containing the same
structure as documented for :ref:`extending-tests-single`.
This way it's possible to run multiple tests per sniff.

Also you can provide further cli arguments on a key -> value base. Where ``runtime-set`` is special,
as it contains a sub array to provide multiple runtime sets.

How sniff tests are implemented
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

We just find all folders below :file:`tests/Fixtures/Standards/Typo3Update/Sniffs` ending with
``Sniff`` and check the structure. They are provided to the test itself through a dataprovider in
phpunit.

We then build the phpcs cli call and execute it against the :file:`InputFileForIssues.php` and
compare the result against the :file:`Expected.json`. Same for :file:`Expected.diff`. The existence
of :file:`Expected.diff` itself will trigger the test for ``phpcbf``.

.. _phpcs: https://github.com/squizlabs/PHP_CodeSniffer
.. _phpunit: https://phpunit.de/