YAML API
YAML is used in TYPO3 for various configurations; most notable are
- Event listeners in
Configuration/
Services. yaml - Dependency injection information in
Configuration/
Services. yaml - Site configuration in
sites/<identifier>/
config. yaml - System extension form configuration
- System extension rte_ckeditor configuration
YamlFileLoader
TYPO3 is using a custom YAML loader for handling YAML in TYPO3 based on the
symfony/yaml package. It is located at
\TYPO3\
and can be used when
YAML parsing is required.
The TYPO3 Core YAML file loader resolves environment variables. Resolving of variables in the loader can be enabled or disabled via flags. For example, when editing the site configuration through the backend interface the resolving of environment variables needs to be disabled to be able to add environment configuration through the interface.
The format for environment variables is %env
. Environment
variables may be used to replace complete values or parts of a value.
The YAML loader class has two flags: PROCESS_
and
PROCESS_
.
PROCESS_
decides whether or not placeholders (PLACEHOLDERS %abc%
) will be resolved.PROCESS_
decides whether or not imports (IMPORTS imports
key) will be resolved.
Use the method Yaml
to make use of the loader in your
extensions:
use TYPO3\CMS\Core\Configuration\Loader\YamlFileLoader;
// ...
(new YamlFileLoader())
->load(string $fileName, int $flags = self::PROCESS_PLACEHOLDERS | self::PROCESS_IMPORTS)
Configuration files can make use of import functionality to reference to the contents of different files.
Example:
imports:
- { resource: "EXT:rte_ckeditor/Configuration/RTE/Processing.yaml" }
- { resource: "misc/my_options.yaml" }
- { resource: "../path/to/something/within/the/project-folder/generic.yaml" }
- { resource: "./**/*.yaml", glob: true }
- { resource: "EXT:core/Tests/**/Configuration/**/SiteConfigs/*.yaml", glob: true }
New in version 12.1
The YAML file loader supports importing of files with glob patterns.
To enable globbing, set the option glob: true
on the import level.
Changed in version 12.0
In TYPO3 v10.4.14 the feature flag yaml
was introduced to enable natural order of YAML imports. For existing
installations it was set to false
(resources are imported in reverse
order), for new installations to true
(resources are imported in
declared order). In TYPO3 v12.0 the feature flag was removed and the
resources are now imported in the exact same order as they are configured in
the importing file.
Custom placeholder processing
It is possible to register custom placeholder processors to allow fetching data
from different sources. To do so, register a custom processor via
config/
:
$GLOBALS['TYPO3_CONF_VARS']['SYS']['yamlLoader']['placeholderProcessors']
[\Vendor\MyExtension\PlaceholderProcessor\CustomPlaceholderProcessor::class] = [];
There are some options available to sort or disable placeholder processors, if necessary:
$GLOBALS['TYPO3_CONF_VARS']['SYS']['yamlLoader']['placeholderProcessors']
[\Vendor\MyExtension\PlaceholderProcessor\CustomPlaceholderProcessor::class] = [
'before' => [
\TYPO3\CMS\Core\Configuration\Processor\Placeholder\ValueFromReferenceArrayProcessor::class
],
'after' => [
\TYPO3\CMS\Core\Configuration\Processor\Placeholder\EnvVariableProcessor::class
],
'disabled' => false,
];
New placeholder processors must implement the
\TYPO3\
.
An implementation may look like the following:
<?php
declare(strict_types=1);
namespace MyVendor\MyExtension\Configuration\Processor\Placeholder;
use TYPO3\CMS\Core\Configuration\Processor\Placeholder\PlaceholderProcessorInterface;
final class ExamplePlaceholderProcessor implements PlaceholderProcessorInterface
{
public function canProcess(string $placeholder, array $referenceArray): bool
{
return str_contains($placeholder, '%example(');
}
public function process(string $value, array $referenceArray)
{
// do some processing
$result = $this->getValue($value);
// Throw this exception if the placeholder can't be substituted
if ($result === null) {
throw new \UnexpectedValueException('Value not found', 1581596096);
}
return $result;
}
private function getValue(string $value): ?string
{
// implement logic to fetch specific values from an external service
// or just add simple mapping logic - whatever is appropriate
$aliases = [
'foo' => 'F-O-O',
'bar' => 'ARRRRR',
];
return $aliases[$value] ?? null;
}
}
This may be used, for example, in the site configuration:
someVariable: '%example(somevalue)%'
anotherVariable: 'inline::%example(anotherValue)%::placeholder'
If a new processor returns a string or number, it may also be used inline as above. If it returns an array, it cannot be used inline since the whole content will be replaced with the new value.