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.
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'].
getDefaultConfigurationRawString()  : string
Helper method of ext_conf_template.txt parsing.
getExtConfTablesWithoutCommentsAsNestedArrayWithoutDots()  : array<string|int, mixed>
Helper method of ext_conf_template.txt parsing.
hasConfiguration()  : bool

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
throws
ExtensionConfigurationExtensionNotConfiguredException

If the extension configuration does not exist

throws
ExtensionConfigurationPathDoesNotExistException

If a requested path in the extension configuration does not exist

Return values
mixed —

The value. Can be a sub array or a single value.

set()

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 system/additional.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

Internal

setAll()

Set new configuration of all extensions and reload TYPO3_CONF_VARS.

public setAll(array<string|int, mixed> $configuration[, bool $skipWriteIfLocalConfigurationDoesNotExist = false ]) : void

This is a "do all" variant of set() for all extensions that prevents writing and loading system/settings.php many times.

Parameters
$configuration : array<string|int, mixed>

Configuration of all extensions

$skipWriteIfLocalConfigurationDoesNotExist : bool = false
Internal

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
Internal

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 $skipWriteIfLocalConfigurationDoesNotExist = 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
$skipWriteIfLocalConfigurationDoesNotExist : bool = false
Internal

getDefaultConfigurationRawString()

Helper method of ext_conf_template.txt parsing.

protected 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
Return values
string

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
bool 

        

        
    




    

    

                            

            

                            
    

        On this page

        
    


            

                    

        

    

        

            
Search results