automated-typo3-update/Readme.rst

195 lines
5.7 KiB
ReStructuredText
Raw Normal View History

.. _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.
2017-03-14 08:40:45 +01:00
- ``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.
2017-03-28 08:40:19 +02:00
- Convert old legacy class *definitions* in extensions to namespaces.
- Convert usage of previously converted class definitions. On first run the definition will be
2017-03-28 08:40:19 +02:00
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
2017-03-28 08:40:19 +02:00
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:
2017-03-28 08:40:19 +02:00
- ``$_EXTKEY,``
2017-03-28 08:40:19 +02:00
- ``$VENDOR . $_EXTKEY,``
2017-03-28 08:40:19 +02:00
- ``'VENDOR.' . $_EXTKEY,``
While the following will not:
2017-03-28 08:40:19 +02:00
- ``$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.
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>
2017-03-28 08:40:19 +02:00
``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
2017-03-28 08:40:19 +02:00
<config name="mappingFile" value="/projects/typo3_installation/vendor/composer/autoload_classaliasmap.php"/>
Example:
.. code:: bash
2017-03-28 08:40:19 +02:00
--runtime-set mappingFile /projects/typo3_installation/vendor/composer/autoload_classaliasmap.php
2017-03-28 08:40:19 +02:00
``vendor``
Configure your vendor through ``ruleset.xml`` or using ``--runtime-set``. Default is
``YourCompany``.
Example:
.. code:: xml
2017-03-28 08:40:19 +02:00
<config name="vendor" value="YourVendor"/>
Example:
.. code:: bash
2017-03-28 08:40:19 +02:00
--runtime-set vendor YourVendor