208 lines
8.0 KiB
ReStructuredText
208 lines
8.0 KiB
ReStructuredText
.. include:: /Includes.rst.txt
|
|
|
|
.. _deprecation-94687:
|
|
|
|
==================================================
|
|
Deprecation: #94687 - Deprecate SoftReferenceIndex
|
|
==================================================
|
|
|
|
See :issue:`94687`
|
|
|
|
Description
|
|
===========
|
|
|
|
The :php:`TYPO3\CMS\Core\Database\SoftReferenceIndex` class combined all core
|
|
soft reference parser implementations into one class. Each and every parser
|
|
had its own method residing in one class. It is now possible to define
|
|
a dedicated class for each parser, as a result :php:`SoftReferenceIndex` is not
|
|
needed anymore and has been therefore marked as deprecated.
|
|
|
|
The related method :php:`\TYPO3\CMS\Backend\Utility\BackendUtility::softRefParserObj()`
|
|
was used to get the according soft reference parser object and was basically a
|
|
factory method. This logic has been moved into
|
|
:php:`TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserFactory`.
|
|
:php:`BackendUtility::softRefParserObj` has been marked as internal in TYPO3 v11
|
|
already. To ease migration, the old static method is still in place and triggers
|
|
a PHP :php:`E_USER_DEPRECATED` error when called.
|
|
|
|
Another tightly coupled method :php:`\TYPO3\CMS\Backend\Utility\BackendUtility::explodeSoftRefParserList()`,
|
|
which was used to parse the comma separated list of soft reference parsers
|
|
and return them as an array, has now also been marked as deprecated. It was mostly used
|
|
for internal purposes. The corresponding logic now resides in the
|
|
:php:`getParsersBySoftRefParserList` method of
|
|
:php:`TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserFactory`.
|
|
|
|
All soft reference parsers are now required to implement the
|
|
:php:`TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserInterface`.
|
|
Not doing so will trigger a PHP :php:`E_USER_DEPRECATED` error. In TYPO3 v12 this will throw an exception.
|
|
|
|
Impact
|
|
======
|
|
|
|
The following class is marked as deprecated. Instantiating this class will
|
|
trigger a PHP :php:`E_USER_DEPRECATED` error.
|
|
|
|
* :php:`TYPO3\CMS\Core\Database\SoftReferenceIndex`
|
|
|
|
The following methods are marked as deprecated. Calling these methods will trigger a PHP :php:`E_USER_DEPRECATED` error.
|
|
|
|
* :php:`\TYPO3\CMS\Backend\Utility\BackendUtility::softRefParserObj()`
|
|
* :php:`\TYPO3\CMS\Backend\Utility\BackendUtility::explodeSoftRefParserList()`
|
|
|
|
Soft reference parsers must implement
|
|
:php:`TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserInterface`.
|
|
Otherwise a PHP :php:`E_USER_DEPRECATED` error will be triggered and an exception will be thrown
|
|
in TYPO3 v12.
|
|
|
|
Affected Installations
|
|
======================
|
|
|
|
* All installations registering user-defined soft reference parsers not
|
|
implementing :php:`TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserInterface`.
|
|
* All installations calling any of the above-mentioned methods.
|
|
* All installations, which are using :php:`TYPO3\CMS\Core\Database\SoftReferenceIndex`
|
|
directly.
|
|
|
|
Migration
|
|
=========
|
|
|
|
Among other methods
|
|
:php:`TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserInterface`
|
|
ensures the method :php:`parse` is implemented. The previously used method name
|
|
:php:`findRef()` can be simply renamed to :php:`parse()`. The first 4 parameters
|
|
:php:`$table`, :php:`$field`, :php:`$uid` and :php:`$content` stay the same, as
|
|
well as the seventh (now fifth) and last parameter :php:`$structurePath`. The
|
|
remaining two parameters :php:`$spKey` (now :php:`$parserKey`) and
|
|
:php:`$spParams` (now :php:`$parameters`) have to be set by the
|
|
:php:`setParserKey()` method, in case they are needed. The key can be retrieved
|
|
by using the :php:`getParserKey()` method.
|
|
|
|
The return type has been changed to an instance of
|
|
:php:`TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserResult`. It
|
|
provides as static factory method simply called :php:`create()`. It expects the
|
|
`content` part of the old array as the first parameter and the `elements` part
|
|
as the second. If there are no matches, one can simply call
|
|
:php:`SoftReferenceParserResult::createWithoutMatches()`.
|
|
|
|
If needed, one could also extend
|
|
:php:`TYPO3\CMS\Core\DataHandling\SoftReference\AbstractSoftReferenceParser`.
|
|
This abstract class comes with the helper method :php:`makeTokenID()` (originally
|
|
in :php:`TYPO3\CMS\Core\Database\SoftReferenceIndex`) and a new method
|
|
:php:`setTokenIdBasePrefix`, which sets the concatenated string for the property
|
|
:php:`tokenID_basePrefix`.
|
|
|
|
Example before:
|
|
|
|
.. code-block:: php
|
|
|
|
class MySoftReferenceParser implements SingletonInterface
|
|
{
|
|
public function findRef($table, $field, $uid, $content, $spKey, $spParams, $structurePath = '')
|
|
{
|
|
...
|
|
|
|
if (!empty($elements)) {
|
|
$resultArray = [
|
|
'content' => $content,
|
|
'elements' => $elements
|
|
];
|
|
return $resultArray;
|
|
}
|
|
|
|
return null;
|
|
}
|
|
}
|
|
|
|
Example after:
|
|
|
|
.. code-block:: php
|
|
|
|
class MySoftReferenceParser implements SoftReferenceParserInterface
|
|
{
|
|
protected string $parserKey = '';
|
|
protected array $parameters = [];
|
|
|
|
public function parse(string $table, string $field, int $uid, string $content, string $structurePath = ''): SoftReferenceParserResult
|
|
{
|
|
...
|
|
|
|
if (!empty($elements)) {
|
|
return SoftReferenceParserResult::create(
|
|
$content,
|
|
$elements
|
|
);
|
|
}
|
|
return SoftReferenceParserResult::createWithoutMatches();
|
|
}
|
|
|
|
/**
|
|
* @param string $parserKey The softref parser key.
|
|
* @param array $parameters Parameters of the softlink parser. Basically this is the content inside optional []-brackets after the softref keys. Parameters are exploded by ";
|
|
*/
|
|
public function setParserKey(string $parserKey, array $parameters): void
|
|
{
|
|
$this->parserKey = $parserKey;
|
|
$this->parameters = $parameters;
|
|
}
|
|
|
|
public function getParserKey(): string
|
|
{
|
|
return $this->parserKey;
|
|
}
|
|
}
|
|
|
|
|
|
Instead of calling :php:`BackendUtility::softRefParserObj()` one should now create
|
|
an instance of :php:`TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserFactory`.
|
|
This factory has a method: :php:`getSoftReferenceParser()`, which expects the
|
|
soft reference key as first argument (just like the BackendUtility method).
|
|
|
|
Example before:
|
|
|
|
.. code-block:: php
|
|
|
|
$softRefObj = BackendUtility::softRefParserObj('typolink');
|
|
|
|
Example after:
|
|
|
|
.. code-block:: php
|
|
|
|
$softReferenceParserFactory = GeneralUtility::makeInstance(SoftReferenceParserFactory::class);
|
|
$softReferenceParser = $softReferenceParserFactory->getSoftReferenceParser('typolink');
|
|
|
|
The method :php:`BackendUtility::explodeSoftRefParserList()` should be replaced by
|
|
instantiating :php:`TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserFactory`
|
|
and calling :php:`getParsersBySoftRefParserList()`. This method expects the
|
|
:php:`$parserList` as first argument, same as in the :php:`BackendUtility`
|
|
The second argument is a fallback configuration array for softref parsers.
|
|
This method returns an iterable of
|
|
:php:`TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserInterface`.
|
|
|
|
Example before:
|
|
|
|
.. code-block:: php
|
|
|
|
$softRefs = BackendUtility::explodeSoftRefParserList($conf['softref']);
|
|
|
|
foreach ($softRefs as $spKey => $spParams) {
|
|
$softRefObj = BackendUtility::softRefParserObj($spKey);
|
|
$resultArray = $softRefObj->findRef($table, $field, $idRecord, $valueField, $spKey, $softRefParams);
|
|
}
|
|
|
|
Example after:
|
|
|
|
.. code-block:: php
|
|
|
|
foreach ($softReferenceParserFactory->getParsersBySoftRefParserList($conf['softref'], $softRefParams) as $softReferenceParser) {
|
|
$parserResult = $softReferenceParser->parse($table, $field, $idRecord, $valueField);
|
|
}
|
|
|
|
|
|
Related
|
|
=======
|
|
|
|
* :doc:`RegisterSoftReferenceParsersViaDI (Feature) <Feature-94741-RegisterSoftReferenceParsersViaDI>`
|
|
* :doc:`RegisterSoftReferenceParsersViaDI (Deprecation) <Deprecation-94741-RegisterSoftReferenceParsersViaDI>`
|
|
|
|
.. index:: Backend, PHP-API, PartiallyScanned, ext:core
|