<markdown>
============================
Reading Configuration Values
============================

[[Solar::config()]] safely reads a configuration group (or group-element)
value from [[Solar::$config]], optionally returning a default value if the
group (or group-element) key does not exist.

-----------------------
Reading An Entire Group
-----------------------

If your Solar.config.php file has this entry ...

{{code: php
    $config['Solar_Example'] = array(
        'flag_a'  => 'these',
        'flag_b'  => 'those',
        'deeper'  => array(
            'deep_1' => 'foo',
            'deep_2' => 'bar',
        ),
    );
}}

... you can retrieve a copy of the entire `Solar_Example` group like this:

{{code: php
    $example = Solar::config(`Solar_Example`);
}}

If the `Solar_Example` group does not exist, the [[Solar::config()]] method
will return an empty array by default. If you want to use a different default
value when `Solar_Example` does not exist, specify a `null` element and the
customized default value:

{{code: php
    $default = 'no such key';
    $value = Solar::config('Solar_Example', null, $default);
}}

Thus, `$value` will be a the string `'no such key'` if the `Solar_Example`
key does not exist in the config file.


------------------------------
Reading A Single Group-Element
------------------------------

If your Solar.config.php file has this entry (identical to the above example)...

{{code: php
    $config['Solar_Example'] = array(
        'flag_a'  => 'these',
        'flag_b'  => 'those',
        'deeper'  => array(
            'deep_1' => 'foo',
            'deep_2' => 'bar',
        ),
    );
}}

... you can retrieve a copy of the 'flag_a' value like this:

{{code: php
    $flag_a = Solar::config('Example', 'flag_a');
}}

If the `Solar_Example` group does not exist, or if the 'flag_a' element does not
exist in the `Solar_Example` group, the config() method will return `null` value by
default. If you want to use a different default value, specify a that value as
the third parameter:

{{code: php
    $flag_a = Solar::config('Example', 'flag_a', 'thars');
}}

Thus, `$flag_a` will be `'thars'` if `Solar::$config['Example']['flag_a']` does not exist.

------------
Deep Reading
------------

The [[Solar::config()]] method only allows you to read groups, or major group
elements. If you have this in your config file (again, identical to above) ...

{{code: php
    $config['Solar_Example'] = array(
        'flag_a'  => 'these',
        'flag_b'  => 'those',
        'deeper'  => array(
            'deep_1' => 'foo',
            'deep_2' => 'bar',
        ),
    );
}}

... you can retrieve the 'deeper' element,

{{code: php
    $deeper = Solar::config('Solar_Example', 'deeper'); // will be an array
}}

... but you cannot retrieve the 'deep_1' sub-element string. In practice, this
is not usually an issue. Although you can always access [[Solar::$config]] if
you need to, nesting often-used config file elements too deeply may be a
signal that you need to re-think your design.


------------------
Mostly Not Needed!
------------------

If your classes extend [[Solar_Base | ]], you won't need to call
Solar::config() very much. This is because the config values are automatically
merged into the [[Solar_Base::$_config | $_config]] property when you
instantiate a Solar_Base-derived class, so you can access the values directly
from inside the object.
</markdown>