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``.

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

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.

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>