Configuration¶

Database Configuration¶

CakePHP expects database configuration details to be in a file at app/Config/database.php. An example database configuration file can be found at app/Config/database.php.default. A finished configuration should look something like this:

class DATABASE_CONFIG {
    public $default = array(
        'datasource'  => 'Database/Mysql',
        'persistent'  => false,
        'host'        => 'localhost',
        'login'       => 'cakephpuser',
        'password'    => 'c4k3roxx!',
        'database'    => 'my_cakephp_project',
        'prefix'      => ''
    );
}

The $default connection array is used unless another connection is specified by the $useDbConfig property in a model. For example, if my application has an additional legacy database in addition to the default one, I could use it in my models by creating a new $legacy database connection array similar to the $default array, and by setting public $useDbConfig = 'legacy'; in the appropriate models.

Fill out the key/value pairs in the configuration array to best suit your needs.

datasource

The name of the datasource this configuration array is for. Examples: Database/Mysql, Database/Sqlserver, Database/Postgres, Database/Sqlite. You can use plugin syntax to indicate plugin datasource to use.

persistent

Whether or not to use a persistent connection to the database. When using SQLServer you should not enable persistent connections as it causes difficult to diagnose crashes in older versions of CakePHP or, as of version 2.10.2, an exception will be thrown.

host

The database server’s hostname (or IP address).

login

The username for the account.

password

The password for the account.

database

The name of the database for this connection to use.

prefix (optional)

The string that prefixes every table name in the database. If your tables don’t have prefixes, set this to an empty string.

port (optional)

The TCP port or Unix socket used to connect to the server.

encoding

Indicates the character set to use when sending SQL statements to the server. This defaults to the database’s default encoding for all databases other than DB2. If you wish to use UTF-8 encoding with mysql/mysqli connections you must use ‘utf8’ without the hyphen.

schema

Used in PostgreSQL database setups to specify which schema to use.

unix_socket

Used by drivers that support it to connect via unix socket files. If you are using PostgreSQL and want to use unix sockets, leave the host key blank.

ssl_key

The file path to the SSL key file. (Only supported by MySQL, requires PHP 5.3.7+).

ssl_cert

The file path to the SSL certificate file. (Only supported by MySQL, requires PHP 5.3.7+).

ssl_ca

The file path to the SSL certificate authority. (Only supported by MySQL, requires PHP 5.3.7+).

settings

An array of key/value pairs that should be sent to the database server as SET commands when the connection is created. This option is only supported by the Mysql, Postgres, and Sqlserver datasources at this time.

At this point, you might want to take a look at the CakePHP Conventions. The correct naming for your tables (and the addition of some columns) can score you some free functionality and help you avoid configuration. For example, if you name your database table big_boxes, your model BigBox, your controller BigBoxesController, everything just works together automatically. By convention, use underscores, lower case, and plural forms for your database table names - for example: bakers, pastry_stores, and savory_cakes.

Additional Class Paths¶

It’s occasionally useful to be able to share MVC classes between applications on the same system. If you want the same controller in both applications, you can use CakePHP’s bootstrap.php to bring these additional classes into view.

By using App::build() in bootstrap.php we can define additional paths where CakePHP will look for classes:

App::build(array(
    'Model' => array(
        '/path/to/models',
        '/next/path/to/models'
    ),
    'Model/Behavior' => array(
        '/path/to/behaviors',
        '/next/path/to/behaviors'
    ),
    'Model/Datasource' => array(
        '/path/to/datasources',
        '/next/path/to/datasources'
    ),
    'Model/Datasource/Database' => array(
        '/path/to/databases',
        '/next/path/to/database'
    ),
    'Model/Datasource/Session' => array(
        '/path/to/sessions',
        '/next/path/to/sessions'
    ),
    'Controller' => array(
        '/path/to/controllers',
        '/next/path/to/controllers'
    ),
    'Controller/Component' => array(
        '/path/to/components',
        '/next/path/to/components'
    ),
    'Controller/Component/Auth' => array(
        '/path/to/auths',
        '/next/path/to/auths'
    ),
    'Controller/Component/Acl' => array(
        '/path/to/acls',
        '/next/path/to/acls'
    ),
    'View' => array(
        '/path/to/views',
        '/next/path/to/views'
    ),
    'View/Helper' => array(
        '/path/to/helpers',
        '/next/path/to/helpers'
    ),
    'Console' => array(
        '/path/to/consoles',
        '/next/path/to/consoles'
    ),
    'Console/Command' => array(
        '/path/to/commands',
        '/next/path/to/commands'
    ),
    'Console/Command/Task' => array(
        '/path/to/tasks',
        '/next/path/to/tasks'
    ),
    'Lib' => array(
        '/path/to/libs',
        '/next/path/to/libs'
    ),
    'Locale' => array(
        '/path/to/locales',
        '/next/path/to/locales'
    ),
    'Vendor' => array(
        '/path/to/vendors',
        '/next/path/to/vendors'
    ),
    'Plugin' => array(
        '/path/to/plugins',
        '/next/path/to/plugins'
    ),
));

Core Configuration¶

Each application in CakePHP contains a configuration file, app/Config/core.php, to determine CakePHP’s internal behavior. This file is a collection of Configure class variable definitions and constant definitions that determine how your application behaves. Before we dive into those particular variables, you’ll need to be familiar with Configure, CakePHP’s configuration registry class.

Configure Class¶

class Configure¶

Despite few things needing to be configured in CakePHP, it’s sometimes useful to have your own configuration rules for your application. In the past you may have defined custom configuration values by defining variable or constants in some files. Doing so forces you to include that configuration file every time you needed to use those values.

CakePHP’s Configure class can be used to store and retrieve application or runtime specific values. Be careful, this class allows you to store anything in it, then use it in any other part of your code: a sure temptation to break the MVC pattern CakePHP was designed for. The main goal of Configure class is to keep centralized variables that can be shared between many objects. Remember to try to live by “convention over configuration” and you won’t end up breaking the MVC structure we’ve set in place.

This class can be called from anywhere within your application, in a static context:

Configure::read('debug');

static Configure::write($key, $value)¶

Parameters:

• $key (string) – The key to write, can be a dot notation value.

• $value (mixed) – The value to store.

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');

Note

The dot notation used in the $key parameter can be used to organize your configuration settings into logical groups.

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

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

You can use Configure::write('debug', $int) to switch between debug and production modes on the fly. This is especially handy for AMF or SOAP interactions where debugging information can cause parsing problems.

static Configure::read($key = null)¶

Parameters:

• $key (string) – The key to read, can be a dot notation value

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

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

Configure::read('Company');

//yields:
array('name' => 'Pizza, Inc.', 'slogan' => 'Pizza for your body and soul');

If $key is left null, all values in Configure will be returned. If the value corresponding to the specified $key does not exist then null will be returned.

static Configure::consume($key)¶

Parameters:

• $key (string) – The key to read, can use be a dot notation value

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

static Configure::check($key)¶

Parameters:

• $key (string) – The key to check.

Used to check if a key/path exists and has not-null value.

New in version 2.3: Configure::check() was added in 2.3

static Configure::delete($key)¶

Parameters:

• $key (string) – The key to delete, can be a dot notation value

Used to delete information from the application’s configuration:

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

static Configure::version¶

Returns the CakePHP version for the current application.

static Configure::config($name, $reader)¶

Parameters:

• $name (string) – The name of the reader being attached.

• $reader (ConfigReaderInterface) – The reader instance being attached.

Attach a configuration reader to Configure. Attached readers can then be used to load configuration files. See Loading configuration files for more information on how to read configuration files.

static Configure::configured($name = null)¶

Parameters:

• $name (string) – The name of the reader to check, if null a list of all attached readers will be returned.

Either check that a reader with a given name is attached, or get the list of attached readers.

static Configure::drop($name)¶

Drops a connected reader object.

Reading and writing configuration files¶

CakePHP comes with two built-in configuration file readers. PhpReader is able to read PHP config files, in the same format that Configure has historically read. IniReader is able to read ini config files. See the PHP documentation for more information on the specifics of ini files. To use a core config reader, you’ll need to attach it to Configure using Configure::config():

App::uses('PhpReader', 'Configure');
// Read config files from app/Config
Configure::config('default', new PhpReader());

// Read config files from another path.
Configure::config('default', new PhpReader('/path/to/your/config/files/'));

You can have multiple readers attached to Configure, each reading different kinds of configuration files, or reading from different types of sources. You can interact with attached readers using a few other methods on Configure. To see which reader aliases are attached you can use Configure::configured():

// Get the array of aliases for attached readers.
Configure::configured();

// Check if a specific reader is attached
Configure::configured('default');

You can also remove attached readers. Configure::drop('default') would remove the default reader alias. Any future attempts to load configuration files with that reader would fail.

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

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

Configure::dump('error.php', 'default', array('Error', 'Exception'));

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

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

Creating your own Configuration readers¶

Since configuration readers are an extensible part of CakePHP, you can create configuration readers in your application and plugins. Configuration readers need to implement the ConfigReaderInterface. This interface defines a read method, as the only required method. If you really like XML files, you could create a simple Xml config reader for you application:

// in app/Lib/Configure/MyXmlReader.php
App::uses('Xml', 'Utility');
class MyXmlReader implements ConfigReaderInterface {
    public function __construct($path = null) {
        if (!$path) {
            $path = APP . 'Config' . DS;
        }
        $this->_path = $path;
    }

    public function read($key) {
        $xml = Xml::build($this->_path . $key . '.xml');
        return Xml::toArray($xml);
    }

    // As of 2.3 a dump() method is also required
    public function dump($key, $data) {
        // code to dump data to file
    }
}

In your app/Config/bootstrap.php you could attach this reader and use it:

App::uses('MyXmlReader', 'Configure');
Configure::config('xml', new MyXmlReader());
...

Configure::load('my_xml');

The read() method of a config reader, must return an array of the configuration information that the resource named $key contains.

interface ConfigReaderInterface¶

Defines the interface used by classes that read configuration data and store it in Configure

ConfigReaderInterface::read($key)¶

Parameters:

• $key (string) – The key name or identifier to load.

This method should load/parse the configuration data identified by $key and return an array of data in the file.

ConfigReaderInterface::dump($key, $data)¶

Parameters:

• $key (string) – The identifier to write to.

• $data (array) – The data to dump.

This method should dump/store the provided configuration data to a key identified by $key.

exception ConfigureException¶

Thrown when errors occur when loading/storing/restoring configuration data. ConfigReaderInterface implementations should throw this exception when they encounter an error.

Inflection Configuration¶

CakePHP’s naming conventions can be really nice - you can name your database table big_boxes, your model BigBox, your controller BigBoxesController, and everything just works together automatically. The way CakePHP knows how to tie things together is by inflecting the words between their singular and plural forms.

There are occasions (especially for our non-English speaking friends) where you may run into situations where CakePHP’s Inflector (the class that pluralizes, singularizes, camelCases, and under_scores) might not work as you’d like. If CakePHP won’t recognize your Foci or Fish, you can tell CakePHP about your special cases.

Inflector::rules('singular', array(
    'rules' => array(
        '/^(bil)er$/i' => '\1',
        '/^(inflec|contribu)tors$/i' => '\1ta'
    ),
    'uninflected' => array('singulars'),
    'irregular' => array('spins' => 'spinor')
));

Inflector::rules('plural', array('irregular' => array('phylum' => 'phyla')));

Bootstrapping CakePHP¶

If you have any additional configuration needs, use CakePHP’s bootstrap file, found in app/Config/bootstrap.php. This file is executed just after CakePHP’s core bootstrapping.

This file is ideal for a number of common bootstrapping tasks:

• Defining convenience functions.

• Registering global constants.

• Defining additional model, view, and controller paths.

• Creating cache configurations.

• Configuring inflections.

• Loading configuration files.

Be careful to maintain the MVC software design pattern when you add things to the bootstrap file: it might be tempting to place formatting functions there in order to use them in your controllers.

Resist the urge. You’ll be glad you did later on down the line.

You might also consider placing things in the AppController class. This class is a parent class to all of the controllers in your application. AppController is a handy place to use controller callbacks and define methods to be used by all of your controllers.