tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-06-28 07:29:26 +02:00
Code Issues Projects Releases Wiki Activity

Config docs improvement: @config and LSB mentions

Browse Source 
Also moved some less important "notes" further down the page.
The doc is still written too much like a technical spec, we need
something that's more accessible to beginners.
This commit is contained in:
Ingo Schommer 2013-03-27 12:08:12 +01:00
parent 315c03872a
commit ccb0155b8f
1 changed files with 47 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
docs/en/topics/configuration.md
View File

@ -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.