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

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

[Solar_Config::get()]: http://solarphp.com/class/Solar_Config/get()
[Solar_Config::$_store]: http://solarphp.com/class/Solar_Config/Properties#_store
-----------------------
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::get(`Solar_Example`);
}}

If the `Solar_Example` group does not exist, the [Solar_Config::get()][] 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::get('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::get('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 get() 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::get('Example', 'flag_a', 'thars');
}}

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

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

The [Solar_Config::get()][] 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::get('Solar_Example', 'deeper'); // will be an array
}}

... but you cannot retrieve the 'deep_1' sub-element string directly. In practice, this
is not usually an issue. 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::get() 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.

[Solar_Base]: http://solarphp.com/class/Solar_Base
</markdown>