mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 14:05:37 +02:00
Review and tidy up of configuration guide
This commit is contained in:
Will Rossiter
Cam Findlay
parent
627cc520d9
commit
bbfc03ad51
@ -1,46 +1,123 @@
|
||||
# Configuration in SilverStripe
|
||||
title: Configuration API
|
||||
summary: SilverStripe's YAML based Configuration API for setting runtime configuration.
|
||||
|
||||
## Introduction
|
||||
# Configuration API
|
||||
|
||||
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.
|
||||
SilverStripe comes with a comprehensive code based configuration system through the [api:Config] class. 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:
|
||||
The Configuration API can be seen as separate from other forms of variables in the SilverStripe system due to three
|
||||
properties API:
|
||||
|
||||
- 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
|
||||
- Configuration is **per class**, not per instance.
|
||||
- Configuration is normally set once during initialization 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):
|
||||
<div class="notice" markdown="1">
|
||||
For providing content editors or CMS users a place to manage configuration see the [SiteConfig](siteconfig) module.
|
||||
</div>
|
||||
|
||||
- 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)
|
||||
## Configuration Properties
|
||||
|
||||
Like statics, configuration values may only contain a literal or constant; neither objects nor expressions are allowed.
|
||||
Configuration values are static properties on any SilverStripe class. These should be at the top of the class and
|
||||
marked with a `@config` docblock. The API documentation will also list the static properties for the class. They should
|
||||
be marked `private static` and follow the `lower_case_with_underscores` structure.
|
||||
|
||||
## Finding Configuration
|
||||
**mysite/code/MyClass.php**
|
||||
|
||||
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.
|
||||
:::php
|
||||
<?php
|
||||
|
||||
## Customizing Configuration (through merging)
|
||||
class MyClass extends Page {
|
||||
|
||||
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
|
||||
/**
|
||||
* @config
|
||||
*/
|
||||
private static $option_one = true;
|
||||
|
||||
As mentioned, the value of any specific class configuration property comes from several sources. These sources do not
|
||||
override each other (except in one specific circumstance) - instead the values from each source are merged together
|
||||
to give the final configuration value, using these rules:
|
||||
/**
|
||||
* @config
|
||||
*/
|
||||
private static $option_two = array();
|
||||
|
||||
// ..
|
||||
}
|
||||
|
||||
## Accessing and Setting Configuration Properties
|
||||
|
||||
This can be done by calling the static method `[api:Config::inst]`, like so:
|
||||
|
||||
:::php
|
||||
$config = Config::inst()->get('MyClass');
|
||||
|
||||
Or through the `config()` object on the class.
|
||||
|
||||
$config = $this->config();
|
||||
|
||||
There are three public methods available on the instance. `get($class, $variable)`, `remove($class, $variable)` and
|
||||
`update($class, $variable, $value)`.
|
||||
|
||||
<div class="notice" markdown="1">
|
||||
There is no "set" method. It is not possible to completely set the value of a classes' property. `update` adds new
|
||||
values that are treated as the highest priority in the merge, and remove adds a merge mask that filters out values.
|
||||
</div>
|
||||
|
||||
To set those configuration options on our previously defined class we can define it in a `YAML` file.
|
||||
|
||||
**mysite/_config/app.yml**
|
||||
|
||||
:::yml
|
||||
MyClass:
|
||||
option_one: false
|
||||
option_two:
|
||||
- Foo
|
||||
- Bar
|
||||
- Baz
|
||||
|
||||
To use those variables in your application code:
|
||||
|
||||
:::php
|
||||
$me = new MyClass();
|
||||
|
||||
echo $me->config()->option_one;
|
||||
// returns false
|
||||
|
||||
echo implode(', ', $me->config()->option_two);
|
||||
// returns 'Foo, Bar, Baz'
|
||||
|
||||
echo Config::inst()->get('MyClass', 'option_one');
|
||||
// returns false
|
||||
|
||||
echo implode(', ', Config::inst()->get('MyClass', 'option_two'));
|
||||
// returns 'Foo, Bar, Baz'
|
||||
|
||||
Config::inst()->update('MyClass', 'option_one', true);
|
||||
|
||||
echo Config::inst()->get('MyClass', 'option_one');
|
||||
// returns true
|
||||
|
||||
// You can also use the static version
|
||||
MyClass::config()->option_two = array(
|
||||
'Qux'
|
||||
);
|
||||
|
||||
echo implode(', ', MyClass::config()->option_one);
|
||||
// returns 'Qux'
|
||||
|
||||
<div class="notice" markdown="1">
|
||||
There is no way currently to restrict read or write access to any configuration property, or influence/check the values
|
||||
being read or written.
|
||||
</div>
|
||||
|
||||
## Configuration Values
|
||||
|
||||
Each configuration property can contain either a literal value (`'foo'`), integer (`2`), boolean (`true`) or an array.
|
||||
If the value is an array, each value in the array may also be one of those types.
|
||||
|
||||
The value of any specific class configuration property comes from several sources. These sources do not override each
|
||||
other - instead the values from each source are merged together to give the final configuration value, using these
|
||||
rules:
|
||||
|
||||
- If the value is an array, each array is added to the _beginning_ of the composite array in ascending priority order.
|
||||
If a higher priority item has a non-integer key which is the same as a lower priority item, the value of those items
|
||||
@ -48,125 +125,100 @@ to give the final configuration value, using these rules:
|
||||
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
|
||||
be raised due to optimisations in the lookup code).
|
||||
|
||||
The exception to this is "false-ish" values - empty arrays, empty strings, etc. When merging a non-false-ish value with a
|
||||
false-ish value, the result will be the non-false-ish value regardless of priority. When merging two false-ish values
|
||||
<div class="alert" markdown="1">
|
||||
The exception to this is "false-ish" values - empty arrays, empty strings, etc. When merging a non-false-ish value with
|
||||
a false-ish value, the result will be the non-false-ish value regardless of priority. When merging two false-ish values
|
||||
the result will be the higher priority false-ish value.
|
||||
</div>
|
||||
|
||||
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 item that is latest is highest priority)
|
||||
- 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.
|
||||
<div class="notice">
|
||||
It is an error to have mixed types of the same named property in different locations. An error will not necessarily
|
||||
be raised due to optimizations in the lookup code.
|
||||
</div>
|
||||
|
||||
## Configuration Masks
|
||||
|
||||
At some of these levels you can also set masks. These remove values from the composite value at their priority point
|
||||
rather than add.
|
||||
|
||||
$actionsWithoutExtra = $this->config()->get(
|
||||
'allowed_actions', Config::UNINHERITED
|
||||
);
|
||||
|
||||
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 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 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 YAML Syntax and Rules
|
||||
|
||||
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.
|
||||
Each module can have a directory immediately underneath the main module directory called `_config/`. Inside this
|
||||
directory you can add YAML files that contain values for the configuration system.
|
||||
|
||||
### Global access
|
||||
<div class="info" markdown="1">
|
||||
The name of the files within the applications `_config` directly are arbitrary. Our examples use
|
||||
`mysite/_config/app.yml` but you can break this file down into smaller files, or clearer patterns like `extensions.yml`,
|
||||
`email.yml` if you want. For add-on's and modules, it is recommended that you name them with `<module_name>.yml`.
|
||||
</div>
|
||||
|
||||
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 `[api:Config::inst()]`, like so:
|
||||
The structure of each YAML file is a series of headers and values separated by YAML document separators.
|
||||
|
||||
$config = Config::inst();
|
||||
:::yml
|
||||
---
|
||||
Name: adminroutes
|
||||
After:
|
||||
- '#rootroutes'
|
||||
- '#coreroutes'
|
||||
---
|
||||
Director:
|
||||
rules:
|
||||
'admin': 'AdminRootController'
|
||||
---
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
### 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:
|
||||
|
||||
:::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; // 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/`.
|
||||
|
||||
Inside this directory you can add yaml files that contain values for the configuration system.
|
||||
|
||||
The structure of each yaml file is a series of headers and values separated by YAML document separators. If there
|
||||
is only one set of values the header can be omitted.
|
||||
|
||||
### The header
|
||||
<div class="info">
|
||||
If there is only one set of values the header can be omitted.
|
||||
</div>
|
||||
|
||||
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 reference path, made up of the module name, the config file name, and a fragment identifier Each path looks a
|
||||
little like a URL and is of this form: `module/file#fragment`.
|
||||
- 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
|
||||
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: `module/file#fragment`.
|
||||
The fragment identifier component of the reference path and the two sets of rules are specified for each value section
|
||||
in the header section that immediately precedes the value section.
|
||||
|
||||
- "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.
|
||||
- "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
|
||||
section in their priority chain rules.
|
||||
|
||||
#### Priorities
|
||||
## Before / After Priorities
|
||||
|
||||
Values for a specific class property can be specified in several value sections across several modules. These values are
|
||||
merged together using the same rules as the configuration system as a whole.
|
||||
|
||||
However unlike the configuration system itself, there is no inherent priority amongst the various value sections.
|
||||
However unlike the configuration system, there is no inherent priority amongst the various value sections.
|
||||
|
||||
Instead, each value section can have rules that indicate priority. Each rule states that this value section
|
||||
must come before (lower priority than) or after (higher priority than) some other value section.
|
||||
Instead, each value section can have rules that indicate priority. Each rule states that this value section must come
|
||||
before (lower priority than) or after (higher priority than) some other value section.
|
||||
|
||||
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:
|
||||
@ -192,46 +244,33 @@ one value section can not be both before _and_ after another. However when you h
|
||||
was a difference in how many wildcards were used, the one with the least wildcards will be kept and the other one
|
||||
ignored.
|
||||
|
||||
A more complex example, taken from framework/_config/routes.yml:
|
||||
|
||||
:::yml
|
||||
---
|
||||
Name: adminroutes
|
||||
Before: '*'
|
||||
After:
|
||||
- '#rootroutes'
|
||||
- '#coreroutes'
|
||||
- '#modelascontrollerroutes'
|
||||
---
|
||||
Director:
|
||||
rules:
|
||||
'admin': 'AdminRootController'
|
||||
---
|
||||
|
||||
The value section above has two rules:
|
||||
|
||||
- It must be merged in before (lower priority than) all other value sections
|
||||
|
||||
- It must be merged in after (higher priority than) any value section with a fragment name of "rootroutes"
|
||||
|
||||
In this case there would appear to be a problem - adminroutes can not be both before all other value sections _and_
|
||||
after value sections with a name of `rootroutes`. However because `\*` has three wildcards
|
||||
(it is the equivalent of `\*/\*#\*`) but `#rootroutes` only has two (it is the equivalent of `\*/\*#rootroutes`).
|
||||
|
||||
In this case `\*` means "every value section _except_ ones that have a fragment name of rootroutes".
|
||||
|
||||
One important thing to note: it is possible to create chains that are unsolvable. For instance, A must be before B,
|
||||
B must be before C, C must be before A. In this case you will get an error when accessing your site.
|
||||
<div class="alert" markdown="1">
|
||||
It is possible to create chains that are unsolvable. For instance, A must be before B, B must be before C, C must be
|
||||
before A. In this case you will get an error when accessing your site.
|
||||
</div>
|
||||
|
||||
#### Exclusionary rules
|
||||
## Exclusionary rules
|
||||
|
||||
Some value sections might only make sense under certain environmental conditions - a class exists, a module is installed,
|
||||
an environment variable or constant is set, or SilverStripe is running in a certain environment mode (live, dev, etc).
|
||||
Some value sections might only make sense under certain environmental conditions - a class exists, a module is
|
||||
installed, an environment variable or constant is set, or SilverStripe is running in a certain environment mode (live,
|
||||
dev, etc).
|
||||
|
||||
To accommodate this, value sections can be filtered to only be used when either a rule matches or doesn't match the
|
||||
current environment.
|
||||
|
||||
To achieve this you add a key to the related header section, either "Only" when the value section should be included
|
||||
only when all the rules contained match, or "Except" when the value section should be included except when all of the
|
||||
To achieve this, add a key to the related header section, either `Only` when the value section should be included
|
||||
only when all the rules contained match, or `Except` when the value section should be included except when all of the
|
||||
rules contained match.
|
||||
|
||||
You then list any of the following rules as sub-keys, with informational values as either a single value or a list.
|
||||
@ -260,111 +299,19 @@ For instance, to add a property to "foo" when a module exists, and "bar" otherwi
|
||||
property: 'bar'
|
||||
---
|
||||
|
||||
Note than when you have more than one rule for a nested fragment, they're joined like
|
||||
|
||||
FRAGMENT_INCLUDED = (ONLY && ONLY) && !(EXCEPT && EXCEPT)
|
||||
|
||||
<div class="alert" markdown="1">
|
||||
When you have more than one rule for a nested fragment, they're joined like
|
||||
`FRAGMENT_INCLUDED = (ONLY && ONLY) && !(EXCEPT && EXCEPT)`.
|
||||
That is, the fragment will be included if all Only rules match, except if all Except rules match.
|
||||
</div>
|
||||
|
||||
Also, due to YAML limitations, having multiple conditions of the same kind (say, two `EnvVarSet` in one "Only" block)
|
||||
|
||||
<div class="alert" markdown="1">
|
||||
Due to YAML limitations, having multiple conditions of the same kind (say, two `EnvVarSet` in one "Only" block)
|
||||
will result in only the latter coming through.
|
||||
|
||||
### The values
|
||||
|
||||
The values section of a YAML configuration file is quite simple - it is simply a nested key / value pair structure
|
||||
where the top level key is the class name to set the property on, and the sub key / value pairs are the properties
|
||||
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:
|
||||
baz:
|
||||
a: 1
|
||||
b: 2
|
||||
|
||||
Notice that we can leave out the header in this case because there is only a single value section within the file.
|
||||
|
||||
## Setting configuration via statics
|
||||
|
||||
The final location that a property can get it's value from is a static set on the associated class.
|
||||
Statics should be considered immutable, and therefore the majority of statics in SilverStripe
|
||||
are marked `private`.
|
||||
|
||||
They should primarily be used to set the initial or default value for any given configuration property. It's also
|
||||
a handy place to hand a docblock to indicate what a property is for. However, it's worth noting that you
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Complex configuration through _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
|
||||
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.
|
||||
|
||||
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)).
|
||||
</div>
|
||||
|
||||
|
||||
## Configuration through the CMS
|
||||
## API Documentation
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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 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.
|
||||
|
||||
## Permissions
|
||||
|
||||
See [security](/topics/security) and [permission](/reference/permission)
|
||||
|
||||
## Resource Usage (Memory and CPU)
|
||||
|
||||
SilverStripe tries to keep its resource usage within the documented limits (see our [server requirements](../installation/server-requirements)).
|
||||
These limits are defined through `memory_limit` and `max_execution_time` in the PHP configuration.
|
||||
They can be overwritten through `ini_set()`, unless PHP is running with the [Suhoshin Patches](http://www.hardened-php.net/)
|
||||
or in "[safe mode](http://php.net/manual/en/features.safe-mode.php)".
|
||||
Most shared hosting providers will have maximum values that can't be altered.
|
||||
|
||||
For certain tasks like synchronizing a large `assets/` folder with all file and folder entries in the database,
|
||||
more resources are required temporarily. In general, we recommend running resource intensive tasks
|
||||
through the [commandline](../topics/commandline), where configuration defaults for these settings are higher or even unlimited.
|
||||
|
||||
SilverStripe can request more resources through `increase_memory_limit_to()` and `increase_time_limit_to()`.
|
||||
If you are concerned about resource usage on a dedicated server (without restrictions imposed through shared hosting providers), you can set a hard limit to these increases through
|
||||
`set_increase_memory_limit_max()` and `set_increase_time_limit_max()`.
|
||||
These values will just be used for specific scripts (e.g. `[api:Filesystem::sync()]`),
|
||||
to raise the limits for all executed scripts please use `ini_set('memory_limit', <value>)`
|
||||
and `ini_set('max_execution_time', <value>)` in your own `_config.php`.
|
||||
* [api:Config]
|
||||
@ -1,37 +1,38 @@
|
||||
# SiteConfig: Global database content
|
||||
title: SiteConfig
|
||||
summary: Content author configuration through the SiteConfig module.
|
||||
|
||||
## Introduction
|
||||
# SiteConfig
|
||||
|
||||
The `[api:SiteConfig]` panel provides a generic interface for managing site wide settings or
|
||||
functionality which is used throughout the site. Out of the box it provides 2 fields 'Site Name' and 'Site Tagline'.
|
||||
The `SiteConfig` module provides a generic interface for managing site wide settings or functionality which is used
|
||||
throughout the site. Out of the box this includes selecting the current site theme, site name and site wide access.
|
||||
|
||||
## Accessing `[api:SiteConfig]` Options
|
||||
## Accessing variables
|
||||
|
||||
You can access `[api:SiteConfig]` options from any SS template by using the function $SiteConfig.FieldName
|
||||
`SiteConfig` options can be accessed from any template by using the $SiteConfig variable.
|
||||
|
||||
:::ss
|
||||
$SiteConfig.Title
|
||||
$SiteConfig.Tagline
|
||||
|
||||
// or
|
||||
|
||||
<% with $SiteConfig %>
|
||||
$Title $AnotherField
|
||||
<% end_with %>
|
||||
$Title $AnotherField
|
||||
<% end_loop %>
|
||||
|
||||
|
||||
Or if you want to access variables in the PHP you can do
|
||||
To access variables in the PHP:
|
||||
|
||||
:::php
|
||||
$config = SiteConfig::current_site_config();
|
||||
$config->Title
|
||||
|
||||
echo $config->Title;
|
||||
|
||||
// returns "Website Name"
|
||||
|
||||
|
||||
## Extending `[api:SiteConfig]`
|
||||
## Extending SiteConfig
|
||||
|
||||
To extend the options available in the panel you can define your own fields via an Extension.
|
||||
To extend the options available in the panel, define your own fields via a [api:DataExtension].
|
||||
|
||||
Create a mysite/code/CustomSiteConfig.php file.
|
||||
**mysite/code/extensions/CustomSiteConfig.php**
|
||||
|
||||
:::php
|
||||
<?php
|
||||
@ -43,26 +44,29 @@ Create a mysite/code/CustomSiteConfig.php file.
|
||||
);
|
||||
|
||||
public function updateCMSFields(FieldList $fields) {
|
||||
$fields->addFieldToTab("Root.Main", new HTMLEditorField("FooterContent", "Footer Content"));
|
||||
$fields->addFieldToTab("Root.Main",
|
||||
new HTMLEditorField("FooterContent", "Footer Content")
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
Then activate the extension.
|
||||
|
||||
Then activate your extension in your [config.yml](/topics/configuration) file.
|
||||
**mysite/_config/app.yml**
|
||||
|
||||
:::yml
|
||||
SiteConfig:
|
||||
extensions:
|
||||
- CustomSiteConfig
|
||||
|
||||
<div class="notice" markdown="1">
|
||||
After adding the class and the YAML change, make sure to rebuild your database by visiting http://yoursite.com/dev/build.
|
||||
You may also need to reload the screen with a `flush=1` i.e http://yoursite.com/admin/settings?flush=1.
|
||||
</div>
|
||||
|
||||
This tells SilverStripe to add the CustomSiteConfig extension to the `[api:SiteConfig]` class.
|
||||
|
||||
After adding those two pieces of code, rebuild your database by visiting http://localhost/dev/build and then reload
|
||||
the admin interface. You may need to reload it with a ?flush=1 on the end.
|
||||
|
||||
You can define as many extensions for `[api:SiteConfig]` as you need. For example if you are developing a module you can define
|
||||
your own global settings for the dashboard.
|
||||
You can define as many extensions for `SiteConfig` as you need. For example, if you're developing a module and what to
|
||||
provide the users a place to configure settings then the `SiteConfig` panel is the place to go it.
|
||||
|
||||
## API Documentation
|
||||
`[api:SiteConfig]`
|
||||
|
||||
* `[api:SiteConfig]`
|
||||
@ -0,0 +1,14 @@
|
||||
title: Environment Variables
|
||||
summary: Site configuration variables such as database connection details, environment type and remote login information.
|
||||
|
||||
# Environment Variables
|
||||
|
||||
Environment specific variables like database connection details, API keys and other server configuration should be kept
|
||||
outside the application code in a separate `_ss_environment.php` file. This file is stored outside the web root and
|
||||
version control for security reasons.
|
||||
|
||||
For more information on the environment file, see the [Environment Management](../../getting_started/environment_management/)
|
||||
documentation.
|
||||
|
||||
Data which isn't sensitive that can be in version control but is mostly static such as constants is best suited to be
|
||||
included through the [Configuration API](configuration) based on the standard environment types (dev / test / live).
|
||||
@ -1,8 +1,5 @@
|
||||
title: Configuration
|
||||
summary: SilverStripe provides several ways to store and modify your application settings. Learn about site wide settings and the YAML based configuration system.
|
||||
introduction: SilverStripe provides several ways to store and modify your application settings. Learn about site wide settings and the YAML based configuration system.
|
||||
|
||||
[CHILDREN]
|
||||
|
||||
## How-to
|
||||
|
||||
[CHILDREN How_To]
|
||||
[CHILDREN]
|
||||
@ -103,6 +103,16 @@ Git and Subversion provide their own facilities for managing dependent repositor
|
||||
This is essentially a variation of the "Archive Download" approach,
|
||||
and comes with the same caveats.
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
|
||||
## Related
|
||||
|
||||
* [Modules Development](/topics/module-development)
|
||||
|
||||
@ -0,0 +1,34 @@
|
||||
title: Resource Usage
|
||||
summary: Manage SilverStripe's memory footprint and CPU usage.
|
||||
|
||||
# Resource Usage
|
||||
|
||||
SilverStripe tries to keep its resource usage within the documented limits
|
||||
(see the [server requirements](../../getting_started/server_requirements)).
|
||||
|
||||
These limits are defined through `memory_limit` and `max_execution_time` in the PHP configuration. They can be
|
||||
overwritten through `ini_set()`, unless PHP is running with the [Suhoshin Patches](http://www.hardened-php.net/)
|
||||
or in "[safe mode](http://php.net/manual/en/features.safe-mode.php)".
|
||||
|
||||
<div class="alert" markdown="1">
|
||||
Most shared hosting providers will have maximum values that can't be altered.
|
||||
</div>
|
||||
|
||||
For certain tasks like synchronizing a large `assets/` folder with all file and folder entries in the database, more
|
||||
resources are required temporarily. In general, we recommend running resource intensive tasks through the
|
||||
[command line](../cli), where configuration defaults for these settings are higher or even unlimited.
|
||||
|
||||
<div class="info" markdown="1">
|
||||
SilverStripe can request more resources through `increase_memory_limit_to()` and `increase_time_limit_to()` functions.
|
||||
</div>
|
||||
|
||||
:::php
|
||||
function myBigFunction() {
|
||||
increase_time_limit_to(400);
|
||||
|
||||
// or..
|
||||
|
||||
set_increase_time_limit_max();
|
||||
|
||||
// ..
|
||||
}
|
||||
Loading…
Reference in New Issue
Block a user