Configuration¶

Loading Additional Configuration Files¶

If your application has many configuration options it can be helpful to split configuration into multiple files. After creating each of the files in your config/ directory you can load them in bootstrap.php:

use Cake\Core\Configure;
use Cake\Core\Configure\Engine\PhpConfig;

Configure::setConfig('default', new PhpConfig());
Configure::load('app', 'default', false);
Configure::load('other_config', 'default');

Environment Variables¶

Many modern cloud providers, like Heroku, let you define environment variables for configuration data. You can configure your CakePHP through environment variables in the 12factor app style. Environment variables allow your application to require less state making your application easier to manage when it is deployed across a number of environments.

As you can see in your app.php, the env() function is used to read configuration from the environment, and build the application configuration. CakePHP uses DSN strings for databases, logs, email transports and cache configurations allowing you to easily vary these libraries in each environment.

For local development, CakePHP leverages dotenv to make local development automatically reload environment variables. Use composer to require this library and then there is a block of code in bootstrap.php that needs to be uncommented to harness it.

You will see a config/.env.example in your application. By copying this file into config/.env and customizing the values you can configure your application.

You should avoid committing the config/.env file to your repository and instead use the config/.env.example as a template with placeholder values so everyone on your team knows what environment variables are in use and what should go in each one.

Once your environment variables have been set, you can use env() to read data from the environment:

$debug = env('APP_DEBUG', false);

The second value passed to the env function is the default value. This value will be used if no environment variable exists for the given key.

General Configuration¶

Below is a description of the variables and how they affect your CakePHP application.

debug

Changes CakePHP debugging output. false = Production mode. No error messages, errors, or warnings shown. true = Errors and warnings shown.

App.namespace

The namespace to find app classes under.

Note

When changing the namespace in your configuration, you will also need to update your composer.json file to use this namespace as well. Additionally, create a new autoloader by running php composer.phar dumpautoload.

App.baseUrl

Un-comment this definition if you don’t plan to use Apache’s mod_rewrite with CakePHP. Don’t forget to remove your .htaccess files too.

App.base

The base directory the app resides in. If false this will be auto detected. If not false, ensure your string starts with a / and does NOT end with a /. For example, /basedir is a valid App.base. Otherwise, the AuthComponent will not work properly.

App.encoding

Define what encoding your application uses. This encoding is used to generate the charset in the layout, and encode entities. It should match the encoding values specified for your database.

App.webroot

The webroot directory.

App.wwwRoot

The file path to webroot.

App.fullBaseUrl

The fully qualified domain name (including protocol) to your application’s root. This is used when generating absolute URLs. By default this value is generated using the $_SERVER environment. However, you should define it manually to optimize performance or if you are concerned about people manipulating the Host header. In a CLI context (from shells) the fullBaseUrl cannot be read from $_SERVER, as there is no webserver involved. You do need to specify it yourself if you do need to generate URLs from a shell (for example, when sending emails).

App.imageBaseUrl

Web path to the public images directory under webroot. If you are using a CDN you should set this value to the CDN’s location.

App.cssBaseUrl

Web path to the public css directory under webroot. If you are using a CDN you should set this value to the CDN’s location.

App.jsBaseUrl

Web path to the public js directory under webroot. If you are using a CDN you should set this value to the CDN’s location.

App.paths

Configure paths for non class based resources. Supports the plugins, templates, locales subkeys, which allow the definition of paths for plugins, view templates and locale files respectively.

App.uploadedFilesAsObjects

Defines whether uploaded files are being represented as objects (true), or arrays (false). This option is being treated as enabled by default. See the File Uploads section in the Request & Response Objects chapter for more information.

Security.salt

A random string used in hashing. This value is also used as the HMAC salt when doing symmetric encryption.

Asset.timestamp

Appends a timestamp which is last modified time of the particular file at the end of asset files URLs (CSS, JavaScript, Image) when using proper helpers. Valid values:

• (bool) false - Doesn’t do anything (default)

• (bool) true - Appends the timestamp when debug is true

• (string) ‘force’ - Always appends the timestamp.

Asset.cacheTime

Sets the asset cache time. This determines the http header Cache-Control’s max-age, and the http header’s Expire’s time for assets. This can take anything that you version of PHP’s strtotime function can take. The default is +1 day.

Using a CDN¶

To use a CDN for loading your static assets, change App.imageBaseUrl, App.cssBaseUrl, App.jsBaseUrl to point the CDN URI, for example: https://mycdn.example.com/ (note the trailing /).

All images, scripts and styles loaded via HtmlHelper will prepend the absolute CDN path, matching the same relative path used in the application. Please note there is a specific use case when using plugin based assets: plugins will not use the plugin’s prefix when absolute ...BaseUrl URI is used, for example By default:

• $this->Helper->assetUrl('TestPlugin.logo.png') resolves to test_plugin/logo.png

If you set App.imageBaseUrl to https://mycdn.example.com/:

• $this->Helper->assetUrl('TestPlugin.logo.png') resolves to https://mycdn.example.com/logo.png.

Database Configuration¶

See the Database Configuration for information on configuring your database connections.

Caching Configuration¶

See the Caching Configuration for information on configuring caching in CakePHP.

Error and Exception Handling Configuration¶

See the Error and Exception Configuration for information on configuring error and exception handlers.

Logging Configuration¶

See the Logging Configuration for information on configuring logging in CakePHP.

Email Configuration¶

See the Email Configuration for information on configuring email presets in CakePHP.

Session Configuration¶

See the Session Configuration for information on configuring session handling in CakePHP.

Routing configuration¶

See the Routes Configuration for more information on configuring routing and creating routes for your application.

Plugin, View Template and Locale Paths¶

Since plugins, view templates and locales are not classes, they cannot have an autoloader configured. CakePHP provides three Configure variables to setup additional paths for these resources. In your config/app.php you can set these variables:

return [
    // More configuration
    'App' => [
        'paths' => [
            'plugins' => [
                ROOT . DS . 'plugins' . DS,
                '/path/to/other/plugins/'
            ],
            'templates' => [
                ROOT . DS . 'templates' . DS,
                ROOT . DS . 'templates2' . DS
            ],
            'locales' => [
                ROOT . DS . 'resources' . DS . 'locales' . DS
            ]
        ]
    ]
];

Paths should end with a directory separator, or they will not work properly.

Writing Configuration data¶

static Cake\Core\Configure::write($key, $value)¶

Use write() to store data in the application’s configuration:

Configure::write('Company.name', 'Pizza, Inc.');
Configure::write('Company.slogan', 'Pizza for your body and soul');

The above example could also be written in a single call:

Configure::write('Company', [
    'name' => 'Pizza, Inc.',
    'slogan' => 'Pizza for your body and soul'
]);

You can use Configure::write('debug', $bool) to switch between debug and production modes on the fly.

Reading Configuration Data¶

static Cake\Core\Configure::read($key = null, $default = null)¶

Used to read configuration data from the application. If a key is supplied, the data is returned. Using our examples from write() above, we can read that data back:

// Returns 'Pizza Inc.'
Configure::read('Company.name');

// Returns 'Pizza for your body and soul'
Configure::read('Company.slogan');

Configure::read('Company');
// Returns:
['name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul'];

// Returns 'fallback' as Company.nope is undefined.
Configure::read('Company.nope', 'fallback');

If $key is left null, all values in Configure will be returned.

static Cake\Core\Configure::readOrFail($key)¶

Reads configuration data just like Cake\Core\Configure::read but expects to find a key/value pair. In case the requested pair does not exist, a RuntimeException will be thrown:

Configure::readOrFail('Company.name');    // Yields: 'Pizza, Inc.'
Configure::readOrFail('Company.geolocation');  // Will throw an exception

Configure::readOrFail('Company');

// Yields:
['name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul'];

Checking to see if Configuration Data is Defined¶

static Cake\Core\Configure::check($key)¶

Used to check if a key/path exists and has non-null value:

$exists = Configure::check('Company.name');

Deleting Configuration Data¶

static Cake\Core\Configure::delete($key)¶

Used to delete information from the application’s configuration:

Configure::delete('Company.name');

Reading & Deleting Configuration Data¶

static Cake\Core\Configure::consume($key)¶

Read and delete a key from Configure. This is useful when you want to combine reading and deleting values in a single operation.

static Cake\Core\Configure::consumeOrFail($key)¶

Consumes configuration data just like Cake\Core\Configure::consume but expects to find a key/value pair. In case the requested pair does not exist, a RuntimeException will be thrown:

Configure::consumeOrFail('Company.name');    // Yields: 'Pizza, Inc.'
Configure::consumeOrFail('Company.geolocation');  // Will throw an exception

Configure::consumeOrFail('Company');

// Yields:
['name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul'];

Loading Configuration Files¶

static Cake\Core\Configure::load($key, $config = 'default', $merge = true)¶

Once you’ve attached a config engine to Configure you can load configuration files:

// Load my_file.php using the 'default' engine object.
Configure::load('my_file', 'default');

Loaded configuration files merge their data with the existing runtime configuration in Configure. This allows you to overwrite and add new values into the existing runtime configuration. By setting $merge to true, values will not ever overwrite the existing configuration.

// config1.php
'Key1' => [
    'Key2' => [
        'Key3' => ['NestedKey1' => 'Value'],
    ],
],

// config2.php
'Key1.Key2' => [
    'Key3' => ['NestedKey2' => 'Value2'],
]

Configure::load('config1', 'default');
Configure::load('config2', 'default', true);

// Now Key1.Key2.Key3 has the value ['NestedKey2' => 'Value2']
// instead of ['NestedKey1' => 'Value', 'NestedKey2' => 'Value2']

Creating or Modifying Configuration Files¶

static Cake\Core\Configure::dump($key, $config = 'default', $keys = [])¶

Dumps all or some of the data in Configure into a file or storage system supported by a config engine. The serialization format is decided by the config engine attached as $config. For example, if the ‘default’ engine is a Cake\Core\Configure\Engine\PhpConfig, the generated file will be a PHP configuration file loadable by the Cake\Core\Configure\Engine\PhpConfig

Given that the ‘default’ engine is an instance of PhpConfig. Save all data in Configure to the file my_config.php:

Configure::dump('my_config', 'default');

Save only the error handling configuration:

Configure::dump('error', 'default', ['Error', 'Exception']);

Configure::dump() can be used to either modify or overwrite configuration files that are readable with Configure::load()

Storing Runtime Configuration¶

static Cake\Core\Configure::store($name, $cacheConfig = 'default', $data = null)¶

You can also store runtime configuration values for use in a future request. Since configure only remembers values for the current request, you will need to store any modified configuration information if you want to use it in subsequent requests:

// Store the current configuration in the 'user_1234' key in the 'default' cache.
Configure::store('user_1234', 'default');

Stored configuration data is persisted in the named cache configuration. See the Caching documentation for more information on caching.

Restoring Runtime Configuration¶

static Cake\Core\Configure::restore($name, $cacheConfig = 'default')¶

Once you’ve stored runtime configuration, you’ll probably need to restore it so you can access it again. Configure::restore() does exactly that:

// Restore runtime configuration from the cache.
Configure::restore('user_1234', 'default');

When restoring configuration information it’s important to restore it with the same key, and cache configuration as was used to store it. Restored information is merged on top of the existing runtime configuration.

Configuration Engines¶

CakePHP provides the ability to load configuration files from a number of different sources, and features a pluggable system for creating your own configuration engines. The built in configuration engines are:

• JsonConfig

• IniConfig

• PhpConfig

By default your application will use PhpConfig.