ExtensionConfiguration
API to get() instance specific extension configuration options.
Extension authors are encouraged to use this API - it is currently a simple wrapper to access TYPO3_CONF_VARS['EXTENSIONS'] but could later become something different in case core decides to store extension configuration elsewhere.
Extension authors must not access TYPO3_CONF_VARS['EXTENSIONS'] on their own.
Extension configurations are often 'feature flags' currently defined by ext_conf_template.txt files. The core (more specifically the install tool) takes care default values and overridden values are properly prepared upon loading or updating an extension.
Note only ->get() is official API and other public methods are low level core internal API that is usually only used by extension manager and install tool.
Table of Contents
Methods
- get() : mixed
- Get a single configuration value, a sub array or the whole configuration.
- getDefaultConfigurationRawString() : string
- Helper method of ext_conf_template.txt parsing.
- set() : void
- Store a new or overwrite an existing configuration value.
- setAll() : void
- Set new configuration of all extensions and reload TYPO3_CONF_VARS.
- synchronizeExtConfTemplateWithLocalConfiguration() : void
- Read values from ext_conf_template, verify if they are in LocalConfiguration.php already and if not, add them.
- synchronizeExtConfTemplateWithLocalConfigurationOfAllExtensions() : void
- If there are new config settings in ext_conf_template of an extension, they are found here and synchronized to LocalConfiguration['EXTENSIONS'].
- getExtConfTablesWithoutCommentsAsNestedArrayWithoutDots() : array<string|int, mixed>
- Helper method of ext_conf_template.txt parsing.
- hasConfiguration() : bool
- removeCommentsAndDotsRecursive() : array<string|int, mixed>
- Helper method of ext_conf_template.txt parsing.
Methods
get()
Get a single configuration value, a sub array or the whole configuration.
public
get(string $extension[, string $path = '' ]) : mixed
Examples: // Simple and typical usage: Get a single config value, or an array if the key is a "TypoScript" // a-like sub-path in ext_conf_template.txt "foo.bar = defaultValue" ->get('myExtension', 'aConfigKey');
// Get all current configuration values, always an array ->get('myExtension');
// Get a nested config value if the path is a "TypoScript" a-like sub-path // in ext_conf_template.txt "topLevelKey.subLevelKey = defaultValue" ->get('myExtension', 'topLevelKey/subLevelKey')
Notes:
- If a configuration or configuration path of an extension is not found, the code tries to synchronize configuration with ext_conf_template.txt first, only if still not found, it will throw exceptions.
- Return values are NOT type safe: A boolean false could be returned as string 0. Cast accordingly.
- This API throws exceptions if the path does not exist or the extension configuration is not available. The install tool takes care any new ext_conf_template.txt values are available TYPO3_CONF_VARS['EXTENSIONS'], a thrown exception indicates a programming error on developer side and should not be caught.
- It is not checked if the extension in question is loaded at all, it's just checked the extension configuration path exists.
- Extensions should typically not get configuration of a different extension.
Parameters
- $extension : string
-
Extension name
- $path : string = ''
-
Configuration path - e.g. "featureCategory/coolThingIsEnabled"
Tags
Return values
mixed —The value. Can be a sub array or a single value.
getDefaultConfigurationRawString()
Helper method of ext_conf_template.txt parsing.
public
getDefaultConfigurationRawString(string $extensionKey) : string
Return content of an extensions ext_conf_template.txt file if the file exists, empty string if file does not exist.
Parameters
- $extensionKey : string
-
Extension key
Return values
stringset()
Store a new or overwrite an existing configuration value.
public
set(string $extension[, mixed|null $value = null ]) : void
This is typically used by core internal low level tasks like the install tool but may become handy if an extension needs to update extension configuration on the fly for whatever reason.
Examples: // Set a full extension configuration ($value could be a nested array, too) ->set('myExtension', ['aFeature' => 'true', 'aCustomClass' => 'css-foo'])
// Unset a whole extension configuration ->set('myExtension')
Notes:
- Do NOT call this at arbitrary places during runtime (eg. NOT in ext_localconf.php or similar). ->set() is not supposed to be called each request since it writes LocalConfiguration each time. This API is however OK to be called from extension manager hooks.
- Values are not type safe, if the install tool wrote them, boolean true could become string 1 on ->get()
- It is not possible to store 'null' as value, giving $value=null or no value at all will unset the path
- Setting a value and calling ->get() afterwards will still return the new value.
- Warning on AdditionalConfiguration.php: If this file overwrites settings, it spoils the ->set() call and values may not end up as expected.
Parameters
- $extension : string
-
Extension name
- $value : mixed|null = null
-
The value. If null, unset the path
setAll()
Set new configuration of all extensions and reload TYPO3_CONF_VARS.
public
setAll(array<string|int, mixed> $configuration[, bool $skipWriteIfLocalConfiguationDoesNotExist = false ]) : void
This is a "do all" variant of set() for all extensions that prevents writing and loading LocalConfiguration many times.
Parameters
- $configuration : array<string|int, mixed>
-
Configuration of all extensions
- $skipWriteIfLocalConfiguationDoesNotExist : bool = false
synchronizeExtConfTemplateWithLocalConfiguration()
Read values from ext_conf_template, verify if they are in LocalConfiguration.php already and if not, add them.
public
synchronizeExtConfTemplateWithLocalConfiguration(string $extensionKey) : void
Used public by extension manager when updating extension
Parameters
- $extensionKey : string
-
The extension to sync
synchronizeExtConfTemplateWithLocalConfigurationOfAllExtensions()
If there are new config settings in ext_conf_template of an extension, they are found here and synchronized to LocalConfiguration['EXTENSIONS'].
public
synchronizeExtConfTemplateWithLocalConfigurationOfAllExtensions([bool $skipWriteIfLocalConfiguationDoesNotExist = false ]) : void
Used when entering the install tool, during installation and if calling ->get() with an extension or path that is not yet found in LocalConfiguration
Parameters
- $skipWriteIfLocalConfiguationDoesNotExist : bool = false
getExtConfTablesWithoutCommentsAsNestedArrayWithoutDots()
Helper method of ext_conf_template.txt parsing.
protected
getExtConfTablesWithoutCommentsAsNestedArrayWithoutDots(string $extensionKey) : array<string|int, mixed>
Poor man version of getDefaultConfigurationFromExtConfTemplateAsValuedArray() which ignores comments and returns ext_conf_template as array where nested keys have no dots.
Parameters
- $extensionKey : string
Return values
array<string|int, mixed>hasConfiguration()
protected
hasConfiguration(string $extension) : bool
Parameters
- $extension : string
Return values
boolremoveCommentsAndDotsRecursive()
Helper method of ext_conf_template.txt parsing.
protected
removeCommentsAndDotsRecursive(array<string|int, mixed> $config) : array<string|int, mixed>
"Comments" from the "TypoScript" parser below are identified by two (!) dots at the end of array keys and all array keys have a single dot at the end, if they have sub arrays. This is cleaned here.
Incoming array: [ 'automaticInstallation' => '1', 'automaticInstallation..' => '# cat=basic/enabled; ...' 'FE.' => [ 'enabled' = '1', 'enabled..' => '# cat=basic/enabled; ...' ] ] Output array: [ 'automaticInstallation' => '1', 'FE' => [ 'enabled' => '1', ]
Parameters
- $config : array<string|int, mixed>
-
Incoming configuration