PHP Class lithium\core\Environment
While those three environments are the most common, you can create any arbitrary environment
with any set of configuration, for example:
embed:lithium\tests\cases\core\EnvironmentTest::testSetAndGetCurrentEnvironment(1-3)
You can then retrieve the configurations using the key name. The correct configuration is
returned, automatically accounting for the current environment:
embed:lithium\tests\cases\core\EnvironmentTest::testSetAndGetCurrentEnvironment(15-15)
Environment also works with subclasses of
Adaptable, allowing you to maintain separate
configurations for database servers, cache adapters, and other environment-specific classes, for
example:
Connections::add('default', array(
'production' => array(
'type' => 'database',
'adapter' => 'MySql',
'host' => 'db1.application.local',
'login' => 'secure',
'password' => 'secret',
'database' => 'app-production'
),
'development' => array(
'type' => 'database',
'adapter' => 'MySql',
'host' => 'localhost',
'login' => 'root',
'password' => '',
'database' => 'app'
)
));
This allows the database connection named
'default' to be connected to a local database in
development, and a production database in production. You can define environment-specific
configurations for caching, logging, even session storage, i.e.:
Cache::config(array(
'userData' => array(
'development' => array('adapter' => 'File'),
'production' => array('adapter' => 'Memcache')
)
));
When the cache configuration is accessed in the application's code, the correct configuration is
automatically used:
$user = User::find($request->id);
Cache::write('userData', "User.{$request->id}", $user->data(), '+5 days');
In this configuration, the above example will automatically send cache writes to the file
system during local development, and to a memcache server in production.
When writing classes that connect to other external resources, you can automatically take
advantage of environment-specific configurations by extending
Adaptable and implementing
your resource-handling functionality in adapter classes.
In addition to managing your environment-specific configurations,
Environment will also help
you by automatically detecting which environment your application is running in. For additional
information, see the documentation for
Environment::is().
Datei anzeigen
Open project: unionofrad/lithium
Class Usage Examples
Protected Properties
| Property |
Type |
Description |
|
| $_configurations |
|
|
|
| $_current |
string |
Holds the name of the current environment under which the application is running. Set by
passing a Request object or $_SERVER or $_ENV array into Environment::set() (which
in turn passes this on to the _detector_ used to determine the correct environment). Can be
tested or retrieved using Environment::is() or Environment::get(). |
|
| $_detector |
callable |
If Environment::is() is used to assign a custom closure for environment detection, a copy
is kept in $_detector. Otherwise, $_detector is null, and the hard-coded detector is
used. |
|
Public Methods
| Method |
Description |
|
|
get ( string $name = null ) : mixed |
Gets the current environment name, a setting associated with the current environment, or the
entire configuration array for the current environment. |
|
|
is ( mixed $detect ) : boolean |
A simple boolean detector that can be used to test which environment the application is
running under. For example Environment::is('development') will return true if
'development' is, in fact, the current environment. |
|
|
reset ( $env = null ) |
Resets the Environment class to its default state, including unsetting the current
environment, removing any environment-specific configurations, and removing the custom
environment detector, if any has been specified. |
|
|
set ( mixed $env, array $config = null ) : array |
Creates, modifies or switches to an existing environment configuration. To create a new
configuration, or to update an existing configuration, pass an environment name and an array
that defines its configuration:
embed:lithium\tests\cases\core\EnvironmentTest::testModifyEnvironmentConfig(1-1) |
|
Protected Methods
| Method |
Description |
|
|
_detector ( ) : object |
Accessor method for Environment::$_detector. If $_detector is unset, returns the default
detector built into the class. For more information on setting and using $_detector, see
the documentation for Environment::is(). The _detector() method is called at the
beginning of the application's life-cycle, when Environment::set() is passed either an
instance of a Request object, or the $_SERVER or $_ENV array. This object (or array)
is then passed onto $_detector, which returns the correct environment. |
|
|
_processDotPath ( $path, &$arrayPointer ) |
|
|
Method Details
_detector()
protected static method
Accessor method for Environment::$_detector. If $_detector is unset, returns the default
detector built into the class. For more information on setting and using $_detector, see
the documentation for Environment::is(). The _detector() method is called at the
beginning of the application's life-cycle, when Environment::set() is passed either an
instance of a Request object, or the $_SERVER or $_ENV array. This object (or array)
is then passed onto $_detector, which returns the correct environment.
|
protected static _detector ( ) : object |
| return |
object |
Returns a callable object (anonymous function) which detects the application's
current environment. |
_processDotPath()
protected static method
get()
public static method
Gets the current environment name, a setting associated with the current environment, or the
entire configuration array for the current environment.
|
public static get ( string $name = null ) : mixed |
|
$name |
string |
The name of the environment setting to retrieve, or the name of an
environment, if that environment's entire configuration is to be retrieved. If
retrieving the current environment name, `$name` should not be passed. |
| return |
mixed |
If `$name` is unspecified, returns the name of the current environment name as
a string (i.e. `'production'`). If an environment name is specified, returns that
environment's entire configuration as an array. |
is()
public static method
This method also handles how the environment is detected at the beginning of the request.
#### Custom Detection
While the default detection rules are very simple (if the 'SERVER_ADDR' variable is set to
127.0.0.1, the environment is assumed to be 'development', or if the string 'test' is
found anywhere in the host name, it is assumed to be 'test', and in all other cases it
is assumed to be 'production'), you can define your own detection rule set easily using a
closure that accepts an instance of the Request object, and returns the name of the correct
environment, as in the following example:
embed:lithium\tests\cases\core\EnvironmentTest::testCustomDetector(1-9)
In the above example, the user-specified closure takes in a Request object, and using the
server data which it encapsulates, returns the correct environment name as a string.
#### Host Mapping
The most common use case is to set the environment depending on host name. For convenience,
the is() method also accepts an array that matches host names to environment names, where
each key is an environment, and each value is either an array of valid host names, or a
regular expression used to match a valid host name.
embed:lithium\tests\cases\core\EnvironmentTest::testDetectionWithArrayMap(1-5)
In this example, a regular expression is being used to match local domains
(i.e. localhost), as well as the built-in .console domain, for console requests. Note
that in the console, the environment can always be overridden by specifying the --env
option.
Then, one or more host names are matched up to 'test' and 'staging', respectively. Note
that no rule is present for production: this is because 'production' is the default value
if no other environment matches.
|
public static is ( mixed $detect ) : boolean |
|
$detect |
mixed |
Either the name of an environment to check against the current, i.e.
`'development'` or `'production'`, or a closure which `Environment` will use
to determine the current environment name, or an array mapping environment names
to host names. |
| return |
boolean |
If `$detect` is a string, returns `true` if the current environment matches
the value of `$detect`, or `false` if no match. If used to set a custom detector,
returns `null`. |
reset()
public static method
Resets the Environment class to its default state, including unsetting the current
environment, removing any environment-specific configurations, and removing the custom
environment detector, if any has been specified.
|
public static reset ( $env = null ) |
|
$env |
|
If set, delete the defined environment only. |
set()
public static method
You can then add to an existing configuration by calling the set() method again with the
same environment name:
embed:lithium\tests\cases\core\EnvironmentTest::testModifyEnvironmentConfig(6-6)
The settings for the environment will then be the aggregate of all set() calls:
embed:lithium\tests\cases\core\EnvironmentTest::testModifyEnvironmentConfig(7-7)
By passing an array to $env, you can assign the same configuration to multiple
environments:
embed:lithium\tests\cases\core\EnvironmentTest::testSetMultipleEnvironments(5-7)
The set() method can also be called to manually set which environment to operate in:
embed:lithium\tests\cases\core\EnvironmentTest::testSetAndGetCurrentEnvironment(5-5)
Finally, set() can accept a Request object, to automatically detect the correct
environment.
embed:lithium\tests\cases\core\EnvironmentTest::testEnvironmentDetection(9-10)
For more information on defining custom rules to automatically detect your application's
environment, see the documentation for Environment::is().
|
public static set ( mixed $env, array $config = null ) : array |
|
$env |
mixed |
The name(s) of the environment(s) you wish to create, update or switch to
(string/array), or a `Request` object or `$_SERVER` / `$_ENV` array used to
detect (and switch to) the application's current environment. |
|
$config |
array |
If creating or updating a configuration, accepts an array of settings.
If the environment name specified in `$env` already exists, the values in
`$config` will be recursively merged with any pre-existing settings. |
| return |
array |
If creating or updating a configuration, returns an array of the environment's
settings. If updating an existing configuration, this will be the newly-applied
configuration merged with the pre-existing values. If setting the environment
itself (i.e. `$config` is unspecified), returns `null`. |
Property Details
$_configurations protected_oe static_oe property
|
protected static $_configurations |
$_current protected_oe static_oe property
Holds the name of the current environment under which the application is running. Set by
passing a Request object or $_SERVER or $_ENV array into Environment::set() (which
in turn passes this on to the _detector_ used to determine the correct environment). Can be
tested or retrieved using Environment::is() or Environment::get().
|
protected static string $_current |
| return |
string |
|
$_detector protected_oe static_oe property
If Environment::is() is used to assign a custom closure for environment detection, a copy
is kept in $_detector. Otherwise, $_detector is null, and the hard-coded detector is
used.
|
protected static callable $_detector |
| return |
callable |
|
