TYPO3 v15 dev-main snapshot ()
This commit is contained in:
+259
@@ -0,0 +1,259 @@
|
||||
.. include:: /Includes.rst.txt
|
||||
|
||||
.. _breaking-107047-1751982363:
|
||||
|
||||
==================================================================
|
||||
Breaking: #107047 - Remove pointer field functionality of TCA flex
|
||||
==================================================================
|
||||
|
||||
See :issue:`107047`
|
||||
|
||||
Description
|
||||
===========
|
||||
|
||||
One of the main features of TCA is the concept of *record types*. This allows
|
||||
using a single table for different purposes and in different contexts. The
|
||||
most well-known examples are the "Page Types" of the :sql:`pages` table and the
|
||||
"Content Types" of the :sql:`tt_content` table. For every specific type, it is
|
||||
possible to define which fields to display and to customize their
|
||||
configuration.
|
||||
|
||||
A special case historically has been plugin registration, which for a long
|
||||
time used the so-called *subtypes* feature of TCA. This was an additional layer
|
||||
below record types, configured using `subtype_value_field` (commonly
|
||||
`list_type`), and optionally `subtypes_addlist` and
|
||||
`subtypes_excludelist` to add or remove fields depending on the selected
|
||||
subtype.
|
||||
|
||||
FlexForms attached to such subtypes were configured using
|
||||
`ds_pointerField` (typically pointing to `list_type,CType`). This came in
|
||||
combination with the corresponding `ds` configuration, which was an array
|
||||
with keys combining the pointer fields, for example:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
'ds_pointerField' => 'list_type,CType',
|
||||
'ds' => [
|
||||
'news_pi1,list' => 'FILE:EXT:news/Configuration/FlexForm.xml',
|
||||
'default' => 'FILE:...'
|
||||
],
|
||||
|
||||
Over recent TYPO3 versions, this approach has been deprecated in favor of
|
||||
using record types exclusively for plugin registration via the `CType` field,
|
||||
making configuration cleaner and easier to understand.
|
||||
|
||||
The special plugin content element (`CType=list`) and the corresponding plugin
|
||||
subtype field `list_type` have been deprecated in
|
||||
:ref:`deprecation-105076-1726923626` and removed in
|
||||
:ref:`breaking-105377-1729513863`.
|
||||
See also :ref:`important-105538-1730752784` for related information about
|
||||
:php:`ExtensionUtility::configurePlugin()` and
|
||||
:php:`ExtensionManagementUtility::addTcaSelectItemGroup()`.
|
||||
|
||||
With this change, support for `ds_pointerField` and the multi-entry
|
||||
`ds` array format has now been removed. The `ds` option now points to
|
||||
a single FlexForm, either directly or via a `FILE:` reference.
|
||||
|
||||
FlexForms must instead be assigned via standard `types` configuration
|
||||
using `columnsOverrides`.
|
||||
|
||||
This also affects the *data structure identifier*, which in the commonly used
|
||||
`tca` type is the `dataStructureKey`. It is now set to `default` if the
|
||||
table does not support record types or no record type-specific configuration
|
||||
exists. Otherwise, the `dataStructureKey` is set to the corresponding
|
||||
record type value, for example `textpic`.
|
||||
|
||||
This change affects the following PSR-14 events:
|
||||
|
||||
* :php-short:`\TYPO3\CMS\Core\Configuration\Event\AfterFlexFormDataStructureIdentifierInitializedEvent`
|
||||
* :php-short:`\TYPO3\CMS\Core\Configuration\Event\AfterFlexFormDataStructureParsedEvent`
|
||||
* :php-short:`\TYPO3\CMS\Core\Configuration\Event\BeforeFlexFormDataStructureIdentifierInitializedEvent`
|
||||
* :php-short:`\TYPO3\CMS\Core\Configuration\Event\BeforeFlexFormDataStructureParsedEvent`
|
||||
|
||||
A fallback for TYPO3 v14 resolves comma-separated `dataStructureKey`
|
||||
values (for example, `list_type,CType`) to `CType`. Such comma-separated
|
||||
keys were used to address flex form fields in page TSconfig overrides via
|
||||
`TCEFORM.<table>.<field>.<dataStructureKey>` and in backend user exclude-field
|
||||
definitions via `<table>:<field>;<dataStructureKey>`. This fallback emits a
|
||||
PHP deprecation notice and is removed in TYPO3 v15, so page TSconfig and
|
||||
exclude-field addressing then use the data structure key as-is (the record
|
||||
type value, for example `textpic`).
|
||||
|
||||
To address circular dependencies during schema building,
|
||||
:php-short:`\TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools` now supports
|
||||
both TCA Schema objects and raw TCA configuration arrays as input. The
|
||||
following methods accept a union type :php:`array|TcaSchema` for the new
|
||||
:php:`$schema` parameter:
|
||||
|
||||
* :php:`getDataStructureIdentifier()`
|
||||
* :php:`parseDataStructureByIdentifier()`
|
||||
* :php:`cleanFlexFormXML()`
|
||||
|
||||
Previously, these methods relied on :php:`$GLOBALS['TCA']` internally, which
|
||||
caused architectural issues. They now operate directly on the provided schema.
|
||||
|
||||
All calls to these methods should provide the :php:`$schema` parameter with
|
||||
either a :php-short:`\TYPO3\CMS\Core\Schema\TcaSchema` instance or a raw TCA
|
||||
configuration array. Since data structure resolution can be customized by
|
||||
extensions, the parameter is not strictly mandatory, but it is strongly
|
||||
recommended to provide it in most cases. An
|
||||
:php-short:`\TYPO3\CMS\Core\Configuration\FlexForm\Exception\InvalidTcaSchemaException`
|
||||
will be thrown if schema resolution is required but no schema is passed.
|
||||
|
||||
This change also enables components like
|
||||
:php-short:`\TYPO3\CMS\Core\Schema\RelationMapBuilder` to use
|
||||
:php-short:`\TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools` during schema
|
||||
building, even when only raw TCA is available.
|
||||
|
||||
For further details on the enhanced FlexFormTools functionality, see
|
||||
:ref:`feature-107047-1751984817`.
|
||||
|
||||
The following class has been removed as it is no longer required:
|
||||
|
||||
* :php-short:`\TYPO3\CMS\Core\Configuration\FlexForm\Exception\InvalidCombinedPointerFieldException`
|
||||
|
||||
Impact
|
||||
======
|
||||
|
||||
**FlexForm Pointer Field Removal**
|
||||
|
||||
Any TCA definition that still uses :php:`ds_pointerField` or a `ds`
|
||||
array with multiple entries (for example `news_pi1,list`) will no longer work
|
||||
and might cause rendering errors.
|
||||
|
||||
**FlexFormTools Schema Parameter**
|
||||
|
||||
All code calling :php-short:`\TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools`
|
||||
methods (:php:`getDataStructureIdentifier()`,
|
||||
:php:`parseDataStructureByIdentifier()`, :php:`cleanFlexFormXML()`) must be
|
||||
updated to provide the required :php:`$schema` parameter.
|
||||
|
||||
Affected installations
|
||||
======================
|
||||
|
||||
**FlexForm Pointer Field Removal**
|
||||
|
||||
All installations using :php:`ds_pointerField` (as the pointer field
|
||||
functionality has been removed entirely) or an array-like structure for
|
||||
`ds` in their TCA field type `flex` configuration.
|
||||
|
||||
**FlexFormTools Schema Parameter**
|
||||
|
||||
All installations with custom code that directly call
|
||||
:php-short:`\TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools` methods
|
||||
without providing the :php:`$schema` parameter.
|
||||
This includes custom extensions or TYPO3 Core patches using these methods.
|
||||
|
||||
A TCA migration automatically converts single-entry `ds` arrays.
|
||||
Multi-entry definitions require manual migration, as they must be aligned with
|
||||
the correct record type configuration, which may require additional
|
||||
configuration changes beforehand.
|
||||
|
||||
Example for single-entry migration:
|
||||
|
||||
**Before:**
|
||||
|
||||
.. code-block:: php
|
||||
:caption: Migration of single-entry ds configuration (before)
|
||||
|
||||
'ds' => [
|
||||
'default' => '<T3DataStructure>...',
|
||||
],
|
||||
|
||||
**After:**
|
||||
|
||||
.. code-block:: php
|
||||
:caption: Migration of single-entry ds configuration (after)
|
||||
|
||||
'ds' => '<T3DataStructure>...',
|
||||
|
||||
Migration
|
||||
=========
|
||||
|
||||
**FlexForm Pointer Field Migration**
|
||||
|
||||
**Before:**
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
'ds_pointerField' => 'list_type,CType',
|
||||
'ds' => [
|
||||
'news_pi1,list' => 'FILE:EXT:news/Configuration/FlexForm.xml',
|
||||
'default' => '<T3DataStructure>...',
|
||||
],
|
||||
|
||||
**After:**
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
'columns' => [
|
||||
'pi_flexform' => [
|
||||
'config' => [
|
||||
'ds' => '<T3DataStructure>...',
|
||||
],
|
||||
],
|
||||
],
|
||||
'types' => [
|
||||
'news_pi1' => [
|
||||
'columnsOverrides' => [
|
||||
'pi_flexform' => [
|
||||
'config' => [
|
||||
'ds' => 'FILE:EXT:news/Configuration/FlexForm.xml',
|
||||
],
|
||||
],
|
||||
],
|
||||
],
|
||||
],
|
||||
|
||||
If no `columnsOverrides` is defined, the default `ds` value of the
|
||||
field configuration will be used as before.
|
||||
|
||||
**FlexFormTools Schema Parameter Migration**
|
||||
|
||||
**Before:**
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
use TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools;
|
||||
use TYPO3\CMS\Core\Utility\GeneralUtility;
|
||||
|
||||
$flexFormTools = GeneralUtility::makeInstance(FlexFormTools::class);
|
||||
$identifier = $flexFormTools->getDataStructureIdentifier(
|
||||
$fieldTca,
|
||||
'tt_content',
|
||||
'pi_flexform',
|
||||
$row
|
||||
);
|
||||
|
||||
**After:**
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
use TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools;
|
||||
use TYPO3\CMS\Core\Schema\TcaSchemaFactory;
|
||||
use TYPO3\CMS\Core\Utility\GeneralUtility;
|
||||
|
||||
$flexFormTools = GeneralUtility::makeInstance(FlexFormTools::class);
|
||||
|
||||
// Option 1: Using TCA Schema object (recommended for normal usage)
|
||||
$tcaSchemaFactory = GeneralUtility::makeInstance(TcaSchemaFactory::class);
|
||||
$tcaSchema = $tcaSchemaFactory->get('tt_content');
|
||||
$identifier = $flexFormTools->getDataStructureIdentifier(
|
||||
$fieldTca,
|
||||
'tt_content',
|
||||
'pi_flexform',
|
||||
$row,
|
||||
$tcaSchema
|
||||
);
|
||||
|
||||
// Option 2: Using raw TCA array (for schema building contexts)
|
||||
$rawTca = $fullTca['tt_content'];
|
||||
$identifier = $flexFormTools->getDataStructureIdentifier(
|
||||
$fieldTca,
|
||||
'tt_content',
|
||||
'pi_flexform',
|
||||
$row,
|
||||
$rawTca
|
||||
);
|
||||
|
||||
.. index:: Backend, FlexForm, TCA, PartiallyScanned, ext:core
|
||||
Reference in New Issue
Block a user