tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 12:05:37 +00:00
Code Issues Projects Releases Wiki Activity

Formatting and docs changes to configuration.md

Browse Source
This commit is contained in:
Ingo Schommer 2013-03-21 19:44:44 +01:00
parent 69ae1f338f
commit 00fb8cf679
1 changed files with 18 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -8,46 +8,33 @@ Configuration can be seen as separate from other forms of variables (such as per
SilverStripe system due to three properties:
- Configuration is per class, not per instance
- Configuration is normally set once during initialisation and then not changed
- Configuration is normally set by a knowledgeable technical user, such as a developer, not the end user
In SilverStripe 3, each class has it's configuration specified as set of named properties and associated values. The
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 (e.g. in `_config.php`)
- Values set via a call to 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
- 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
## The merge
Each named class configuration property can contain either
- An array
- A non-array value
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
As mentioned, this value of any specific class configuration property comes from several sources. These sources do not
@ -58,7 +45,6 @@ to give the final configuration value, using these rules:
If a higher priority item has a non-integer key which is the same as a lower priority item, the value of those items
is merged using these same rules, and the result of the merge is located in the same location the higher priority item
would be if there was no key clash. Other than in this key-clash situation, within the particular array, order is preserved.
- If the value is not an array, the highest priority value is used without any attempt to merge
It is an error to have mixed types of the same named property in different locations (but an error will not necessarily
@ -70,24 +56,17 @@ 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 (e.g. via `_config.php`)
- The configuration values taken from the YAML files in `_config/` directories (internally sorted in before / after order, where
- 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 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
- The composite configuration value of the parent class of this class
At some of these levels you can also set masks. These remove values from the composite value at their priority point rather than add.
They are much simpler. They consist of a list of key / value pairs. When applied against the current composite value
- If the composite value is a sequential array, any member of that array that matches any value in the mask is removed
- 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
@ -105,11 +84,10 @@ done by calling the static method Config::inst(), like so:
There are then three public methods available on the instance so obtained
- Config#get() returns the value of a specified classes' property
- Config#remove() removes information from the value of a specified classes' property.
To remove all values, use the `Config::anything()` placeholder.
- Config#update() adds additional information into the value of a specified classes' property
- Config#remove() removes information from the value of a specified classes' property
Note that there is no "set" method. Because of the merge, it is not possible to completely set the value of a classes'
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.
@ -121,14 +99,22 @@ which accesses the Config class with the class parameter already set.
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
:::php
$this->config()->get('my_property');
$this->config()->update('my_other_property', 2);
Or even shorter:
:::php
$this->config()->my_property;
$this->config()->my_other_property = 2;
## Setting configuration via YAML files
Each module can (in fact, should - see below for why) have a directory immediately underneath the main module
@ -144,9 +130,7 @@ is only one set of values the header can be omitted.
Each value section of a YAML file has
- A reference path, made up of the module name, the config file name, and a fragment identifier
- A set of rules for the value section's priority relative to other value sections
- A set of rules that might exclude the value section from being used
The fragment identifier component of the reference path and the two sets of rules are specified for each
@ -181,6 +165,7 @@ must come before (lower priority than) or after (higher priority than) some othe
To specify these rules you add an "After" and/or "Before" key to the relevant header section. The value for these
keys is a list of reference paths to other value sections. A basic example:
:::yml
---
Name: adminroutes
After: 'framework/routes#rootroutes', 'framework/routes#coreroutes'
@ -201,6 +186,7 @@ ignored.
A more complex example, taken from framework/_config/routes.yml
:::yml
---
Name: adminroutes
Before: '*'
@ -241,18 +227,15 @@ contained match.
You then list any of the following rules as sub-keys, with informational values as either a single value or a list.
- 'classexists', in which case the value(s) should be classes that must exist
- 'moduleexists', in which case the value(s) should be modules that must exist
- 'environment', in which case the value(s) should be one of "live", "test" or "dev" to indicate the SilverStripe
mode the site must be in
- 'envvarset', in which case the value(s) should be environment variables that must be set
- 'constantdefined', in which case the value(s) should be constants that must be defined
For instance, to add a property to "foo" when a module exists, and "bar" otherwise, you could do this:
:::yml
---
Only:
moduleexists: 'MyFineModule'
@ -276,6 +259,7 @@ and values themselves (where values of course can themselves be nested hashes).
A simple example setting a property called "foo" to the scalar "bar" on class "MyClass", and a property called "baz"
to a nested array on class "MyOtherClass".
:::yml
MyClass:
foo: 'bar'
MyOtherClass:
@ -318,34 +302,6 @@ 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)).
## Legacy configuration - static methods
Some configuration has not yet been moved to the SilverStripe 3 configuration system. The primary way to set this
configuration is to call a static method or set a static variable directly within a _config.php file.
You can call most static methods from _config.php - classes will be loaded as required. Here's a list - **this is
incomplete - please add to it** *Try to keep it in alphabetical order too! :)*
| Call | | Description |
| ---- | | ----------- |
| Authenticator::register_authenticator($authenticator);| | Enable an authentication method (for more details see [security](/topics/security)). |
| Authenticator::set_default_authenticator($authenticator); | | Modify tab-order on login-form.|
| BBCodeParser::disable_autolink_urls(); | | Disables plain hyperlinks from being turned into links when bbcode is parsed. |
| DataObject::$create_table_options['MySQLDatabase'] = 'ENGINE=MyISAM';| | Set the default database engine to MyISAM (versions 2.4 and below already default to MyISAM) |
| Debug::send_errors_to(string $email) | | Send live errors on your site to this address (site has to be in 'live' mode using Director::set_environment_type(live) for this to occur |
| Director::set_environment_type(string dev,test,live) | | Sets the environment type (e.g. dev site will show errors, live site hides them and displays a 500 error instead) |
| Director::set_dev_servers(array('localhost', 'dev.mysite.com)) | | Set servers that should be run in dev mode (see [debugging](debugging)) |
| Director::addRules(int priority, array rules) | | Create a number of URL rules to be checked against when SilverStripe tries to figure out how to display a page. See cms/_config.php for some examples. Note: Using ->something/ as the value for one of these will redirect the user to the something/ page. |
| Email::setAdminEmail(string $adminemail) | | Sets the admin email for the site, used if there is no From address specified, or when you call Email::getAdminEmail() |
| Email::send_all_emails_to(string $email) | | Sends all emails to this address. Useful for debugging your email sending functions |
| Email::cc_all_emails_to(string $email) | | Useful for CC'ing all emails to someone checking correspondence |
| Email::bcc_all_emails_to(string $email) | | BCC all emails to this address, similar to CC'ing emails (above) |
| Requirements::set_suffix_requirements(false); | | Disable appending the current date to included files |
| Security::encrypt_passwords($encrypt_passwords); | | Specify if you want store your passwords in clear text or encrypted (for more details see [security](/topics/security)) |
| Security::set_password_encryption_algorithm($algorithm, $use_salt);| | If you choose to encrypt your passwords, you can choose which algorithm is used to and if a salt should be used to increase the security level even more (for more details see [security](/topics/security)). |
| Security::setDefaultAdmin('admin','password'); | | Set default admin email and password, helpful for recovering your password |
| SSViewer::set_theme(string $themename) | | Choose the default theme for your site |
## Constants
Some constants are user-defineable within *_ss_environment.php*.