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

Review and tidy up of configuration guide

Browse Source
This commit is contained in:
Will Rossiter 2014-10-17 23:09:37 +13:00 committed by Cam Findlay
parent 627cc520d9
commit bbfc03ad51
6 changed files with 275 additions and 269 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

423
docs/en/02_Developer_Guides/04_Configuration/00_Configuration.md
View File

@ -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. SilverStripe comes with a comprehensive code based configuration system through the [api:Config] class. It primarily
It primarily relies on declarative [YAML](http://en.wikipedia.org/wiki/YAML) files, relies on declarative [YAML](http://en.wikipedia.org/wiki/YAML) files, and falls back to procedural PHP code, as well
and falls back to procedural PHP code, as well as PHP static variables. 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 The Configuration API can be seen as separate from other forms of variables in the SilverStripe system due to three
SilverStripe system due to three properties: properties API:
- Configuration is per class, not per instance - Configuration is **per class**, not per instance.
- Configuration is normally set once during initialisation and then not changed - 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 - 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 <div class="notice" markdown="1">
values at any given time are calculated by merging several sources using rules explained below. For providing content editors or CMS users a place to manage configuration see the [SiteConfig](siteconfig) module.
These sources are as follows (in highest -> lowest priority order): </div>
- Values set via a call to `[api:Config::update()]` ## Configuration Properties
- 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)
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, :::php
there's no exhaustive list. All configurable statics are marked with a `@config` docblock <?php
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) 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 * @config
to give the final configuration value, using these rules: */
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 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 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. 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 - 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 <div class="alert" markdown="1">
false-ish value, the result will be the non-false-ish value regardless of priority. When merging two false-ish values 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. 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: The locations that configuration values are taken from in highest -> lowest priority order are:
- Any values set via a call to Config#update - 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
the item that is latest is highest priority) 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 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 - 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 - 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 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 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 - 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 YAML Syntax and Rules
configuration values.
Note: There is no way currently to restrict read or write access to any configuration property, Each module can have a directory immediately underneath the main module directory called `_config/`. Inside this
or influence/check the values being read or written. 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 The structure of each YAML file is a series of headers and values separated by YAML document separators.
done by calling the static method `[api:Config::inst()]`, like so:
$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: <div class="info">
If there is only one set of values the header can be omitted.
- Config#get() returns the value of a specified classes' property </div>
- 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
Each value section of a YAML file has: 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 for the value section's priority relative to other value sections
- A set of rules that might exclude the value section from being used - 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 The fragment identifier component of the reference path and the two sets of rules are specified for each value section
value section in the header section that immediately preceeds the value section. in the header section that immediately precedes 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`.
- "module" is the name of the module this YAML file is in. - "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). - "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. - "fragment" is a specified identifier. It is specified by putting a `Name: {fragment}` key / value pair into the
section. If you don't specify a name, a random one will be assigned. 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 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. 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 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. 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 Instead, each value section can have rules that indicate priority. Each rule states that this value section must come
must come before (lower priority than) or after (higher priority than) some other value section. 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 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: 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 was a difference in how many wildcards were used, the one with the least wildcards will be kept and the other one
ignored. 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: 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 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" - 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_ 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 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`). (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". 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, <div class="alert" markdown="1">
B must be before C, C must be before A. In this case you will get an error when accessing your site. 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, Some value sections might only make sense under certain environmental conditions - a class exists, a module is
an environment variable or constant is set, or SilverStripe is running in a certain environment mode (live, dev, etc). 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 To accommodate this, value sections can be filtered to only be used when either a rule matches or doesn't match the
current environment. current environment.
To achieve this you add a key to the related header section, either "Only" when the value section should be included 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 only when all the rules contained match, or `Except` when the value section should be included except when all of the
rules contained match. 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. 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' property: 'bar'
--- ---
Note than when you have more than one rule for a nested fragment, they're joined like <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) `FRAGMENT_INCLUDED = (ONLY && ONLY) && !(EXCEPT && EXCEPT)`.
That is, the fragment will be included if all Only rules match, except if all Except rules match. 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. will result in only the latter coming through.
</div>
### 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)).
## Configuration through the CMS ## API Documentation
SilverStripe framework does not provide a method to set configuration via a web panel. * [api:Config]
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`.

56
docs/en/02_Developer_Guides/04_Configuration/01_SiteConfig.md
View File

@ -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 The `SiteConfig` module provides a generic interface for managing site wide settings or functionality which is used
functionality which is used throughout the site. Out of the box it provides 2 fields 'Site Name' and 'Site Tagline'. 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 :::ss
$SiteConfig.Title $SiteConfig.Title
$SiteConfig.Tagline $SiteConfig.Tagline
// or
<% with $SiteConfig %> <% with $SiteConfig %>
$Title $AnotherField $Title $AnotherField
<% end_with %> <% end_loop %>
To access variables in the PHP:
Or if you want to access variables in the PHP you can do
:::php :::php
$config = SiteConfig::current_site_config(); $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
<?php <?php
@ -43,26 +44,29 @@ Create a mysite/code/CustomSiteConfig.php file.
); );
public function updateCMSFields(FieldList $fields) { 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 :::yml
SiteConfig: SiteConfig:
extensions: extensions:
- CustomSiteConfig - 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. 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.
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.
## API Documentation ## API Documentation
`[api:SiteConfig]`
* `[api:SiteConfig]`

14
docs/en/02_Developer_Guides/04_Configuration/03_Environment_Variables.md Normal file
View File

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

7
docs/en/02_Developer_Guides/04_Configuration/index.md
View File

@ -1,8 +1,5 @@
title: Configuration 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. 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] [CHILDREN]
## How-to
[CHILDREN How_To]

10
docs/en/02_Developer_Guides/05_Extending/01_Modules.md
View File

@ -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, This is essentially a variation of the "Archive Download" approach,
and comes with the same caveats. 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 ## Related
* [Modules Development](/topics/module-development) * [Modules Development](/topics/module-development)

34
docs/en/02_Developer_Guides/08_Performance/05_Resource_Usage.md Normal file
View File

@ -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();
// ..
}