diff --git a/docs/en/topics/configuration.md b/docs/en/topics/configuration.md index fe1d90b78..69ba3ca85 100644 --- a/docs/en/topics/configuration.md +++ b/docs/en/topics/configuration.md @@ -3,6 +3,8 @@ ## Introduction SilverStripe 3 comes with a comprehensive code based configuration system. +It primarily relies on declarative [YAML](http://en.wikipedia.org/wiki/YAML) files, +and falls back to procedural PHP code, as well as PHP static variables. Configuration can be seen as separate from other forms of variables (such as per-member or per-site settings) in the SilverStripe system due to three properties: @@ -15,24 +17,23 @@ In SilverStripe 3, each class has it's configuration specified as set of named p values at any given time are calculated by merging several sources using rules explained below. These sources are as follows (in highest -> lowest priority order): - - Values set via a call to Config#update + - Values set via a call to `[api:Config::update()]` - Values taken from YAML files in specially named directories - Statics set on an "extra config source" class (such as an extension) named the same as the name of the property (optionally) - Statics set on the class named the same as the name of the property - The parent of the class (optionally) -Some things to keep in mind when working with the configuration system +Like statics, configuration values may only contain a literal or constant; neither objects nor expressions are allowed. - - Like statics, configuration values may only contain a literal or constant; neither objects nor expressions are - allowed - - The list of properties that can be set on a class is not pre-defined, and there is no way to introspect the list - of properties or the expected type of any property - - There is no way currently to restrict read or write access to any configuration property - - There is no way currently to mutate or intercept read or write access to any configuration property - that is - (for example) there is no support for getters or setters +## Finding Configuration -## The merge +Since configuration settings are just static properties on any SilverStripe class, +there's no exhaustive list. All configurable statics are marked with a `@config` docblock +though, so you can search for them in the codebase. The same docblock will also contain +a description of the configuration setting. + +## Customizing Configuration (through merging) Each named class configuration property can contain either an array or a non-array value. If the value is an array, each value in the array may also be one of those three types @@ -57,7 +58,7 @@ the result will be the higher priority false-ish value. The locations that configuration values are taken from in highest -> lowest priority order are: - Any values set via a call to Config#update -- The configuration values taken from the YAML files in _config directories (internally sorted in before / after order, where +- The configuration values taken from the YAML files in `_config/` directories (internally sorted in before / after order, where the item that is latest is highest priority) - Any static set on an "additional static source" class (such as an extension) named the same as the name of the property - Any static set on the class named the same as the name of the property @@ -69,15 +70,18 @@ They are much simpler. They consist of a list of key / value pairs. When applied - If the composite value is an associative array, any member of that array that matches both the key and value of any pair in the mask is removed - If the composite value is not an array, if that value matches any value in the mask it is removed -## Reading and updating configuration via the Config class +## Reading and updating via the Config class The Config class is both the primary manner of getting configuration values and one of the locations you can set -configuration values +configuration values. + +Note: There is no way currently to restrict read or write access to any configuration property, +or influence/check the values being read or written. ### Global access The first thing you need to do to use the Config class is to get the singleton instance of that class. This can be -done by calling the static method Config::inst(), like so: +done by calling the static method `[api:Config::inst()]`, like so: $config = Config::inst(); @@ -92,18 +96,18 @@ Note that there is no "set" method. Because of the merge, it is not possible to property (unless you're setting it to a true-ish literal). Update adds new values that are treated as the highest priority in the merge, and remove adds a merge mask that filters out values. -### Short-hand reading and updating configuration for instances of Object children +### Short-hand access Within any subclass of Object you can call the config() instance method to get an instance of a proxy object which accesses the Config class with the class parameter already set. -For instance, instead of writing +For instance, instead of writing: :::php Config::inst()->get($this->class, 'my_property'); Config::inst()->update($this->class, 'my_other_property', 2); -You can write +You can write: :::php $this->config()->get('my_property'); @@ -112,13 +116,18 @@ You can write Or even shorter: :::php - $this->config()->my_property; - $this->config()->my_other_property = 2; + $this->config()->my_property; // getter + $this->config()->my_other_property = 2; // setter + +This also works statically: + + MyClass::config()->my_property; // getter + MyClass::config()->my_property = 2; // setter ## Setting configuration via YAML files Each module can (in fact, should - see below for why) have a directory immediately underneath the main module -directory called "_config". +directory called `_config/`. Inside this directory you can add yaml files that contain values for the configuration system. @@ -138,15 +147,12 @@ value section in the header section that immediately preceeds the value section. #### Reference paths and fragment identifiers -Each value section has a reference path. Each path looks a little like a URL, and is of this form: +Each value section has a reference path. Each path looks a little like a URL, +and is of this form: `module/file#fragment`. - module/file#fragment - -"module" is the name of the module this YAML file is in - -"file" is the name of this YAML file, stripped of the extension (so for routes.yml, it would be routes) - -"fragment" is a specified identifier. It is specified by putting a `Name: {fragment}` key / value pair into the header + - "module" is the name of the module this YAML file is in + - "file" is the name of this YAML file, stripped of the extension (so for routes.yml, it would be routes) + - "fragment" is a specified identifier. It is specified by putting a `Name: {fragment}` key / value pair into the header section. If you don't specify a name, a random one will be assigned. This reference path has no affect on the value section itself, but is how other header sections refer to this value @@ -282,18 +288,18 @@ do not have to define a static for a property to be valid. ## Configuration as a module marker Configuration files also have a secondary sub-role. Modules are identified by the `[api:ManifestBuilder]` by the -presence of a _config directory (or a _config.php file) as a top level item in the module directory. +presence of a `_config/` directory (or a `_config.php` file) as a top level item in the module directory. Although your module may choose not to set any configuration, it must still have a _config directory to be recognised as a module by the `[api:ManifestBuilder]`, which is required for features such as autoloading of classes and template detection to work. -## _config.php +## Complex configuration through _config.php -In addition to the configuration system described above, each module can provide a file called _config.php +In addition to the configuration system described above, each module can provide a file called `_config.php` immediately within the module top level directory. -These _config.php files will be included at initialisation, and are a useful way to set legacy configuration +These `_config.php` files will be included at initialisation, and are a useful way to set legacy configuration or set configuration based on rules that are more complex than can be encoded in YAML files. However they should generally be avoided when possible, as they slow initialisation. @@ -301,29 +307,27 @@ However they should generally be avoided when possible, as they slow initialisat Please note that this is the only place where you can put in procedural code - all other functionality is wrapped in classes (see [common-problems](/installation/common-problems)). -## Constants -Some constants are user-defineable within *_ss_environment.php*. +## Configuration through the CMS -## No GUI configuration - -SilverStripe framework does not provide a method to set configuration via a web panel - -This lack of a configuration-GUI is on purpose, as we'd like to keep developer-level options where they belong (into +SilverStripe framework does not provide a method to set most system-level configuration via a web panel. +This lack of a configuration GUI is on purpose, as we'd like to keep developer-level options where they belong (into code), without cluttering up the interface. See this core forum discussion ["The role of the CMS"](http://www.silverstripe.org/archive/show/532) for further reasoning. -In addition to these principle, some settings are - * Author-level configuration like interface language or date/time formats can be performed in the CMS "My Profile" section (`admin/myprofile`). - * Group-related configuration like `[api:HTMLEditorField]` settings can be found in the "Security" section (`admin/security`). +The GUI-based configuation is limited to the following: + + * Author-level configuration like interface language or date/time formats can be performed in the CMS "My Profile" section + * Group-related configuration like `[api:HTMLEditorField]` settings can be found in the "Security" section * Site-wide settings like page titles can be set (and extended) on the root tree element in the CMS "Content" section (through the [siteconfig](/reference/siteconfig) API). + * Any configuration interfaces added by custom code, for example through `getCMSFields()` ## Constants and the _ss_environment.php File See [environment-management](/topics/environment-management). -## User-level: Member-object +## User preferences in the `Member` class All user-related preferences are stored as a property of the `[api:Member]`-class (and as a database-column in the *Member*-table). You can "mix in" your custom preferences by using `[api:DataObject]` for details.