mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-09-29 12:49:06 +02:00
Config docs improvement: @config and LSB mentions
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:
parent
315c03872a
commit
ccb0155b8f
@ -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.
|
||||
|
Loading…
Reference in New Issue
Block a user