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-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/