1.. include:: ../../Includes.txt
2
3==============================================================
4Feature: #90267 - Custom placeholder processing in site config
5==============================================================
6
7See :issue:`90267`
8
9Description
10===========
11
12The Yaml import for site configuration was changed to allow custom placeholder processors.
13
14
15Impact
16======
17
18It is now possible to register a new placeholder processor:
19
20:file:`LocalConfiguration.php`:
21
22.. code-block:: php
23
24   $GLOBALS['TYPO3_CONF_VARS']['SYS']['yamlLoader']['placeholderProcessors'][\Vendor\MyExtension\PlaceholderProcessor\CustomPlaceholderProcessor::class] = [];
25
26There are some options available to sort or disable placeholder processors if necessary.
27
28.. code-block:: php
29
30   $GLOBALS['TYPO3_CONF_VARS']['SYS']['yamlLoader']['placeholderProcessors'][\Vendor\MyExtension\PlaceholderProcessor\CustomPlaceholderProcessor::class] = [
31      'before' => [
32         \TYPO3\CMS\Core\Configuration\Processor\Placeholder\ValueFromReferenceArrayProcessor::class
33      ],
34      'after' => [
35         \TYPO3\CMS\Core\Configuration\Processor\Placeholder\EnvVariableProcessor::class
36      ],
37      'disabled' => false
38   ];
39
40New placeholder processors must implement the :php:`\TYPO3\CMS\Core\Configuration\Processor\Placeholder\PlaceholderProcessorInterface`
41
42Placeholders look mostly like functions.
43So an implementation may look like the following:
44
45.. code-block:: php
46
47   class ExamplePlaceholderProcessor implements PlaceholderProcessorInterface
48   {
49      public function canProcess(string $placeholder, array $referenceArray): bool
50      {
51         return strpos($placeholder, '%example(') !== false;
52      }
53
54      public function process(string $value, array $referenceArray)
55      {
56         // do some processing
57         $result = $this->getValue($value);
58
59         // Throw this exception if the placeholder can't be substituted
60         if (!$envVar) {
61            throw new \UnexpectedValueException('Value not found', 1581596096);
62         }
63         return $result;
64      }
65   }
66
67
68This may be used like the following in the site configuration:
69
70.. code-block:: yaml
71
72   someVariable: '%example(somevalue)%'
73   anotherVariable: 'inline::%example(anotherValue)%::placeholder'
74
75If a new processor returns a string or number, it may also be used inline as above.
76If it returns an array, it cannot be used inline since the whole content will be replaced with the new value.
77
78
79.. index:: Backend, PHP-API, ext:core
80