Deprecation: #94687 - Deprecate SoftReferenceIndex¶
See forge#94687
Description¶
The 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 SoftReferenceIndex
is not
needed anymore and has been therefore marked as deprecated.
The related method \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
TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserFactory
.
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 E_USER_DEPRECATED
error when called.
Another tightly coupled method \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
getParsersBySoftRefParserList
method of
TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserFactory
.
All soft reference parsers are now required to implement the
TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserInterface
.
Not doing so will trigger a 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 E_USER_DEPRECATED
error.
TYPO3\CMS\Core\Database\SoftReferenceIndex
The following methods are marked as deprecated. Calling these methods will trigger a PHP E_USER_DEPRECATED
error.
\TYPO3\CMS\Backend\Utility\BackendUtility::softRefParserObj()
\TYPO3\CMS\Backend\Utility\BackendUtility::explodeSoftRefParserList()
Soft reference parsers must implement
TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserInterface
.
Otherwise a a 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
TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserInterface
.All installations calling any of the above-mentioned methods.
All installations, which are using
TYPO3\CMS\Core\Database\SoftReferenceIndex
directly.
Migration¶
Among other methods
TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserInterface
ensures the method parse
is implemented. The previously used method name
findRef()
can be simply renamed to parse()
. The first 4 parameters
$table
, $field
, $uid
and $content
stay the same, as
well as the seventh (now fifth) and last parameter $structurePath
. The
remaining two parameters $spKey
(now $parserKey
) and
$spParams
(now $parameters
) have to be set by the
setParserKey()
method, in case they are needed. The key can be retrieved
by using the getParserKey()
method.
The return type has been changed to an instance of
TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserResult
. It
provides as static factory method simply called 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
SoftReferenceParserResult::createWithoutMatches()
.
If needed, one could also extend
TYPO3\CMS\Core\DataHandling\SoftReference\AbstractSoftReferenceParser
.
This abstract class comes with the helper method makeTokenID()
(originally
in TYPO3\CMS\Core\Database\SoftReferenceIndex
) and a new method
setTokenIdBasePrefix
, which sets the concatenated string for the property
tokenID_basePrefix
.
Example before:
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:
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 BackendUtility::softRefParserObj()
one should now create
an instance of TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserFactory
.
This factory has a method: getSoftReferenceParser()
, which expects the
soft reference key as first argument (just like the BackendUtility method).
Example before:
$softRefObj = BackendUtility::softRefParserObj('typolink');
Example after:
$softReferenceParserFactory = GeneralUtility::makeInstance(SoftReferenceParserFactory::class);
$softReferenceParser = $softReferenceParserFactory->getSoftReferenceParser('typolink');
The method BackendUtility::explodeSoftRefParserList()
should be replaced by
instantiating TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserFactory
and calling getParsersBySoftRefParserList()
. This method expects the
$parserList
as first argument, same as in the BackendUtility
The second argument is a fallback configuration array for softref parsers.
This method returns an iterable of
TYPO3\CMS\Core\DataHandling\SoftReference\SoftReferenceParserInterface
.
Example before:
$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:
foreach ($softReferenceParserFactory->getParsersBySoftRefParserList($conf['softref'], $softRefParams) as $softReferenceParser) {
$parserResult = $softReferenceParser->parse($table, $field, $idRecord, $valueField);
}