Configuration File

Solar::start() reads a single configuration file to set itself up. This file is a regular PHP file that returns a single associative array keyed on Solar class names; each of those array elements is itself composed of an associative array suitable for passing as Solar constructor parameters.

The config file contains all of the "system" settings for Solar, including the site-specific default configuration options you want to use for all Solar classes. Solar reads the configuration file values into Solar::$config the first time you call Solar::start(). If Solar cannot find the config file, it will throw an exception.

Note: As a matter of convenience, having a config file is hard to beat. However, you can call Solar::start() with different parameter types, and Solar will use that alternative parameter as the data source. See the Solar::start() documentation for more information. For purposes of getting started, though, we'll continue to assume that we're using a config file as the data source.

Name and Location

The config file, by convention, is called Solar.config.php, but you can call it anything you like. You can even have multiple config files and switch between them.

You should always keep your configuration file outside of the document root (i.e., the web root). This is because it will contain sensitive information like passwords.

Format

The config file is just another PHP script. The only requirement is that it return an array as its last command. Thus, the simplest possible config file looks like this:

<?php
return array();
?>

The array is composed of key-value pairs, where the initial key is the name of a Solar class, and the value is itself an array of key-value pairs where the key is a configuration option name and the value is the value for the options. These configuration options differ from class to class, so you should refer the specific documentation for the class in question when configuring it.

Simple Example

As a simple example, the Solar arch-class can be configured this way ...

<?php
// Solar.config.php
return array(

    // config options for the Solar class
    'Solar' => array(

        // ini settings
        'ini_set' => array(
            'error_reporting' => true,
            'html_errors'     => true,
        ),

        // custom start scripts
        'start' => array(
            '/path/to/custom/start.php',
        ),

        // custom stop scripts
        'stop' => array(
            '/path/to/custom/stop.php',
        ),

    ),

);
?>

... or (as an equivalent) this way:

<?php
$config = array();

$config['Solar']['ini_set']['display_errors'] = true;
$config['Solar']['ini_set']['html_errors']    = true;
$config['Solar']['start'][]                   = '/path/to/custom/start.php';
$config['Solar']['stop'][]                    = '/path/to/custom/stop.php';

return $config;
?>

Remember, you always have to return an array from the config file; if you do not, Solar won't be able to receive the config values you entered.

Complex Example

The following is a more-complex example of a Solar configuration file. Even though we use variables to ease the setup process, none of those variables will be seen by the rest of Solar (unless you use the global keyword) because the config file is processed in an isolated scope.

<?php
/**
 * Empty base array.
 */
$config = array();

/**
 * A path location outside the web root.
 */
$safedir = '/path/to/config';

/**
 * Default database connection via the 'Solar_Sql' class.
 */
$config['Solar_Sql'] = array(
    'adapter'  => 'Solar_Sql_Adapter_Sqlite',
);

/**
 * The SQLite adapter uses these default values.
 */
$config['Solar_Sql_Adapter_Sqlite'] = array(
    'name' => "$safedir/solar.sqlite",
);

/**
 * User authentication source via 'Solar_Auth'.
 */
$config['Solar_Auth'] = array(
    'adapter' => 'Solar_Auth_Adapter_Htpasswd',
);

/**
 * The Htpasswd adapter uses these default values.
 */
$config['Solar_Auth_Adapter_Htpasswd'] = array(
    'file' => "$safedir/htpasswd.conf",
);

/**
 * Done!
 */
return $config;
?>

For really complex config files, you can use regular PHP code if you need it. For example, your config file can set different values depending on which server or host it's on by examining $_SERVER['SERVER_NAME'].