automated-typo3-update/Readme.rst

.. _highlight: bash

About
=====

Our goal is to provide an automated migration for TYPO3 updates.

This should include source code modifications like adjusting old legacy class names to new ones.

Requirements
============

- ``composer`` needs to be installed and inside your ``$PATH``.

Installation
============

Run::

    make install

and copy the ``vendor/composer/autoload_classaliasmap.php`` generated by ``composer`` in your TYPO3
installation to ``LegacyClassnames.php`` in the root of this project.

Usage
=====

Run::

    ./vendor/bin/phpcbf <path>

This will run the auto fixer recursive for ``<path>`` fixing all issues.

Afterwards you should run::

    ./vendor/bin/phpcs <path>

To get information about possible issues that were not autofixed.

What's included?
================

Currently we can migrate calls to old legacy class names of the TYPO3 core like ``Tx_Extbase...`` to
new ones like ``\TYPO3\Extbase\...``. This is done for:

- PHPDocuments, like Includes and annotations for IDEs.

- Inheritance like ``extends`` and ``implements``.

- Static calls like ``t3lib_div::`` to ``\TYPO3\Core\Utility\GeneralUtility``.

- Static call also checks for ``::class``, as technically we just look before the ``::``.

- Typehints in methods and function like injects.

- ``instanceof`` checks.

- Inline comments for IDEs, e.g. ``/* @var $configurationManager
  Tx_Extbase_Configuration_ConfigurationManager */``

- Instantiation through ``new``.

- Instantiation through ``makeInstance``. Only Classnames in Strings are supported, no ``::class``.

- Instantiation through ``ObjectManager``, check afterwards as this is static and all function calls
  using ``get`` and ``create`` will be adjusted. Might be useful to exclude this sniff and run it
  separately.
  Only Classnames in Strings are supported, no ``::class``.

- ``use`` statements.

- ``catch`` of legacy class names.

- Convert old legacy class *definitions* in extensions to namespaces.

- Convert usage of previously converted class definitions. On first run the definition will be
  converted, on second run the usage. This is due to the fact, that PHPCS might find the definition
  after the usage, so please run twice.

  *NOTE* The configured file will be updated after each run, for each converted class, trait and
  interface definition. See options.

- Add missing vendor to plugin and module registrations and configurations.
  You might want to set this to non fixable and warning if you already provide the vendor inside a
  single Variable, together with your extension key, as this is not recognized. So the following
  will be recognized:

  - ``$_EXTKEY,``

  - ``$VENDOR . $_EXTKEY,``

  - ``'VENDOR.' . $_EXTKEY,``

  While the following will not:

  - ``$key = 'Vendor.' . $_EXTKEY;``

Also we check for the following deprecated calls:

- Check for ``create`` on ``ObjectManager``, which is "stupid" just all ``create`` calls are marked
  with a warning.

Beside the features above which are covered by ``phpcs`` and phpcbf``, the following linting is also
available to generate a report of possible issues and during coding through ``phpcs``:

- Check for usage of removed functions.
  The functions are configured via yaml files. The location of them is configurable, default is
  inside the standard itself, and we try to deliver all information.
  For configuration options see ``removedFunctionConfigFiles``.

What does it look like?
=======================

.. code::

   $ ./vendor/bin/phpcs -p --colors -s <path>
   E


   FILE: <path>
   ----------------------------------------------------------------------
   FOUND 5 ERRORS AFFECTING 5 LINES
   ----------------------------------------------------------------------
    8 | ERROR | [x] Legacy classes are not allowed; found
      |       |   backend_toolbarItem
      |       |   (Typo3Update.LegacyClassnames.Inheritance.legacyClassname)
   14 | ERROR | [x] Legacy classes are not allowed; found TYPO3backend
      |       |   (Typo3Update.LegacyClassnames.DocComment.legacyClassname)
   16 | ERROR | [x] Legacy classes are not allowed; found TYPO3backend
      |       |   (Typo3Update.LegacyClassnames.TypeHint.legacyClassname)
   48 | ERROR | [x] Legacy classes are not allowed; found t3lib_extMgm
      |       |   (Typo3Update.LegacyClassnames.StaticCall.legacyClassname)
   61 | ERROR | [x] Legacy classes are not allowed; found t3lib_div
      |       |   (Typo3Update.LegacyClassnames.StaticCall.legacyClassname)
   ----------------------------------------------------------------------
   PHPCBF CAN FIX THE 5 MARKED SNIFF VIOLATIONS AUTOMATICALLY
   ----------------------------------------------------------------------

   Time: 35ms; Memory: 5Mb

Configuration
=============

Configuration is done through PHPCS Standards, e.g. provide a custom ``ruleset.xml`` or customize
the provided one.

``legacyExtensions``
    Configures which extension names are legacy. Used to provide further checks and warnings about
    possible legacy code. E.g. inside of non auto migrated situations.

    Example:

.. code:: xml

  <rule ref="Typo3Update.LegacyClassnames.Instanceof">
      <properties>
          <property name="legacyExtensions" type="array" value="Extbase,Fluid,Frontend,Core"/>
      </properties>
  </rule>

Typo3Update.LegacyClassnames.DocComment: ``allowedTags``
    Configures which tags are checked for legacy class names.

    Example:

.. code:: xml

   <rule ref="Typo3Update.LegacyClassnames.DocComment">
       <properties>
           <property name="allowedTags" type="array" value="@param,@return,@var,@see,@throws"/>
       </properties>
   </rule>

``mappingFile``
    Configure where the `LegacyClassnames.php` is located, through ``ruleset.xml`` or using
    ``--runtime-set``. Default is `LegacyClassnames.php` in the project root.

    Example:

.. code:: xml

    <config name="mappingFile" value="/projects/typo3_installation/vendor/composer/autoload_classaliasmap.php"/>

Example:

.. code:: bash

    --runtime-set mappingFile /projects/typo3_installation/vendor/composer/autoload_classaliasmap.php

``vendor``
    Configure your vendor through ``ruleset.xml`` or using ``--runtime-set``. Default is
    ``YourCompany``.

    Example:

.. code:: xml

    <config name="vendor" value="YourVendor"/>

Example:

.. code:: bash

    --runtime-set vendor YourVendor

``removedFunctionConfigFiles``
    Configure your vendor through ``ruleset.xml`` or using ``--runtime-set``. Default is
    ``Configuration/Removed/Functions/*.yaml`` inside the standard itself.
    Globing is used, so placeholders like ``*`` are possible, see
    https://secure.php.net/manual/en/function.glob.php

    Example:

.. code:: xml

    <config name="removedFunctionConfigFiles" value="/Some/Absolute/Path/*.yaml"/>

Example:

.. code:: bash

    --runtime-set removedFunctionConfigFiles "/Some/Absolute/Path/*.yaml"