TASK: Document yaml structure
* To ease contributions and modifications Relates: #54
This commit is contained in:
parent
7c5d95d0e0
commit
74eb4dde20
1 changed files with 96 additions and 7 deletions
|
@ -1,3 +1,4 @@
|
||||||
|
.. _highlight: yaml
|
||||||
.. _configuration:
|
.. _configuration:
|
||||||
|
|
||||||
Configuration
|
Configuration
|
||||||
|
@ -7,6 +8,13 @@ Configuration is done through PHPCS Standards, e.g. provide a custom :file:`rule
|
||||||
project using a :file:`phpcs.xml.dist`. As this is just a PHPCS-Standard, the official documentation
|
project using a :file:`phpcs.xml.dist`. As this is just a PHPCS-Standard, the official documentation
|
||||||
applies.
|
applies.
|
||||||
|
|
||||||
|
Also some configuration is done through yaml files, see :ref:`configuration-yaml-files`.
|
||||||
|
|
||||||
|
.. _configuration-options:
|
||||||
|
|
||||||
|
Options
|
||||||
|
-------
|
||||||
|
|
||||||
All options available in :file:`ruleset.xml` are also available in your :file:`phpcs.xml` files, as
|
All options available in :file:`ruleset.xml` are also available in your :file:`phpcs.xml` files, as
|
||||||
already documented by phpcs itself. Therefore this documentation will just mention
|
already documented by phpcs itself. Therefore this documentation will just mention
|
||||||
:file:`ruleset.xml`.
|
:file:`ruleset.xml`.
|
||||||
|
@ -22,7 +30,7 @@ The following configuration options are available:
|
||||||
.. _configuration-legacyExtensions:
|
.. _configuration-legacyExtensions:
|
||||||
|
|
||||||
legacyExtensions
|
legacyExtensions
|
||||||
----------------
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Configures which extension names are legacy. Used to provide further checks and warnings about
|
Configures which extension names are legacy. Used to provide further checks and warnings about
|
||||||
possible legacy code. All class usages starting with ``Tx_<ExtensionName>`` where ExtensionName is
|
possible legacy code. All class usages starting with ``Tx_<ExtensionName>`` where ExtensionName is
|
||||||
|
@ -44,7 +52,7 @@ Example:
|
||||||
.. _configuration-allowedTags:
|
.. _configuration-allowedTags:
|
||||||
|
|
||||||
allowedTags
|
allowedTags
|
||||||
-----------
|
^^^^^^^^^^^
|
||||||
|
|
||||||
Only used inside Sniff ``Typo3Update.LegacyClassnames.DocComment``.
|
Only used inside Sniff ``Typo3Update.LegacyClassnames.DocComment``.
|
||||||
|
|
||||||
|
@ -66,7 +74,7 @@ Example:
|
||||||
.. _configuration-mappingFile:
|
.. _configuration-mappingFile:
|
||||||
|
|
||||||
mappingFile
|
mappingFile
|
||||||
-----------
|
^^^^^^^^^^^
|
||||||
|
|
||||||
For auto migrating usages of old class names, a PHP file with a mapping is required. The file has to
|
For auto migrating usages of old class names, a PHP file with a mapping is required. The file has to
|
||||||
be in the composer structure :file:`autoload_classaliasmap.php`.
|
be in the composer structure :file:`autoload_classaliasmap.php`.
|
||||||
|
@ -91,7 +99,7 @@ Using ``runtime-set``:
|
||||||
.. _configuration-vendor:
|
.. _configuration-vendor:
|
||||||
|
|
||||||
vendor
|
vendor
|
||||||
------
|
^^^^^^
|
||||||
|
|
||||||
Used while adding namespaces to legacy class definitions and updating plugin and module
|
Used while adding namespaces to legacy class definitions and updating plugin and module
|
||||||
registrations. Default is ``YourCompany`` to enable you to search and replace afterwards.
|
registrations. Default is ``YourCompany`` to enable you to search and replace afterwards.
|
||||||
|
@ -115,7 +123,7 @@ Example:
|
||||||
.. _configuration-removedFunctionConfigFiles:
|
.. _configuration-removedFunctionConfigFiles:
|
||||||
|
|
||||||
removedFunctionConfigFiles
|
removedFunctionConfigFiles
|
||||||
--------------------------
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Configure where to look for configuration files defining the removed functions and methods. Default
|
Configure where to look for configuration files defining the removed functions and methods. Default
|
||||||
is ``Configuration/Removed/Functions/*.yaml`` inside the standard itself. We already try to deliver
|
is ``Configuration/Removed/Functions/*.yaml`` inside the standard itself. We already try to deliver
|
||||||
|
@ -138,7 +146,7 @@ Example:
|
||||||
.. _configuration-removedConstantConfigFiles:
|
.. _configuration-removedConstantConfigFiles:
|
||||||
|
|
||||||
removedConstantConfigFiles
|
removedConstantConfigFiles
|
||||||
--------------------------
|
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Configure where to look for configuration files defining the removed constants. Default is
|
Configure where to look for configuration files defining the removed constants. Default is
|
||||||
``Configuration/Removed/Functions/*.yaml`` inside the standard itself. We already try to deliver as
|
``Configuration/Removed/Functions/*.yaml`` inside the standard itself. We already try to deliver as
|
||||||
|
@ -160,7 +168,7 @@ Example:
|
||||||
.. _configuration-removedTypoScriptConfigFiles:
|
.. _configuration-removedTypoScriptConfigFiles:
|
||||||
|
|
||||||
removedTypoScriptConfigFiles
|
removedTypoScriptConfigFiles
|
||||||
----------------------------
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
Configure where to look for configuration files defining the removed TypoScript object identifiers.
|
Configure where to look for configuration files defining the removed TypoScript object identifiers.
|
||||||
Default is ``Configuration/Removed/TypoScript/*.yaml`` inside the standard itself.
|
Default is ``Configuration/Removed/TypoScript/*.yaml`` inside the standard itself.
|
||||||
|
@ -178,3 +186,84 @@ Example:
|
||||||
.. code:: bash
|
.. code:: bash
|
||||||
|
|
||||||
--runtime-set removedTypoScriptConfigFiles "/Some/Absolute/Path/*.yaml"
|
--runtime-set removedTypoScriptConfigFiles "/Some/Absolute/Path/*.yaml"
|
||||||
|
|
||||||
|
.. _configuration-yaml-files:
|
||||||
|
|
||||||
|
YAML Files
|
||||||
|
----------
|
||||||
|
|
||||||
|
YAML files are used to configure removed constants, function / methods and TypoScript. We decided to
|
||||||
|
go with yaml files here, to ease adding stuff in the future. It's a simple format and everyone can
|
||||||
|
contribute.
|
||||||
|
|
||||||
|
You can configure the paths to look up the files through the specific options, documented above.
|
||||||
|
|
||||||
|
This section will cover the structure of the various yaml files.
|
||||||
|
|
||||||
|
General structure
|
||||||
|
^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The basic structure is the same for all parts. Inside a file you have to provide an array for each
|
||||||
|
TYPO3 version::
|
||||||
|
|
||||||
|
'7.0':
|
||||||
|
styles.insertContent:
|
||||||
|
replacement: 'Either remove usage of styles.insertContent or a...'
|
||||||
|
docsUrl: 'https://docs.typo3.org/typo3cms/extensions/core/7.6/Changelog/7.0...'
|
||||||
|
'7.1':
|
||||||
|
\TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController->includeTCA:
|
||||||
|
replacement: 'Full TCA is always loaded during bootstrap in ...'
|
||||||
|
docsUrl: 'https://docs.typo3.org/typo3cms/extensions/core/7.6/Changelog/7...'
|
||||||
|
|
||||||
|
In above example the TypoScript ``styles.insertContent`` was removed in TYPO3 version *7.0*.
|
||||||
|
Below a TYPO3 version each entry is a removed function or TypoScript part of TYPO3. The key is used
|
||||||
|
to lookup matchings in the source code. Specific parsing is documented below.
|
||||||
|
|
||||||
|
All entries consists of a ``replacement`` and ``docsUrl`` entry.
|
||||||
|
|
||||||
|
The ``replacement`` can either be ``null`` or a string. If it's null we will show that this part is
|
||||||
|
removed without any replacement.
|
||||||
|
If you provide a string, this will be displayed to help during migrations.
|
||||||
|
|
||||||
|
The ``docsUrl`` is displayed in addition, so everyone can take a deeper look at the change, the
|
||||||
|
effects and how to migrate.
|
||||||
|
|
||||||
|
Also the TYPO3 core team references the forge issues in each change, where you can find the pull
|
||||||
|
requests.
|
||||||
|
|
||||||
|
Constants and Functions
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
Special parsing is done for the keys identifying removed constants and functions.
|
||||||
|
|
||||||
|
Always provide the fully qualified class namespace. Seperate the constant or method by ``::`` if
|
||||||
|
it's possible to access it static, otherwise use ``->`` to indicate it's an instance method.
|
||||||
|
|
||||||
|
This is used to check only matching calls.
|
||||||
|
|
||||||
|
Two examples::
|
||||||
|
|
||||||
|
'7.0':
|
||||||
|
\TYPO3\CMS\Core\Utility\GeneralUtility::loadTCA:
|
||||||
|
replacement: null
|
||||||
|
docsUrl: 'https://docs.typo3.org/typo3cms/extensions/core/7.6/Ch...'
|
||||||
|
\TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController->includeTCA:
|
||||||
|
replacement: 'Full TCA is always loaded during bootstrap in FE, th...'
|
||||||
|
docsUrl: 'https://docs.typo3.org/typo3cms/extensions/core/7.6/Change...'
|
||||||
|
|
||||||
|
TypoScript
|
||||||
|
^^^^^^^^^^
|
||||||
|
|
||||||
|
Use ``new`` in front of, to declare the entry as OBJECT, e.g. a cObject.
|
||||||
|
Only matching types will be checked in source code.
|
||||||
|
|
||||||
|
Two examples::
|
||||||
|
|
||||||
|
'7.0':
|
||||||
|
styles.insertContent:
|
||||||
|
replacement: 'Either remove usage of styles.insertContent or add a sni...'
|
||||||
|
docsUrl: 'https://docs.typo3.org/typo3cms/extensions/core/7.6/Changelog...'
|
||||||
|
'7.1':
|
||||||
|
new HRULER:
|
||||||
|
replacement: 'Any installation should migrate to alternatives such as F...'
|
||||||
|
docsUrl: 'https://docs.typo3.org/typo3cms/extensions/core/7.6/Changelog...'
|
||||||
|
|
Loading…
Reference in a new issue