<markdown>
==========
Base Class
==========

The [[Class::Solar_Base | ]] class is a lightweight base class from which all
other Solar classes descend (not including exceptions, which descend from the
[[Class::Solar_Exception | ]] class). This base class provides:

* A standard [[Solar_Base::__construct() | ]] method that reads from the
  [[config file]], then combines the instantiation-time [[constructor parameters]]
  with the default config values for the class.

* A [[Solar_Base::$_config | ]] property to collect configuration values for
  the class and its parents.

* An [[Solar_Base::_exception() | ]] method for finding and returning
  exceptions with localized message text.

* A [[Solar_Base::locale() | ]] method for finding and returning localized
  text strings.

* An [[Solar_Base::apiVersion() | ]] method for finding the API version of the
  class.

-------------------------
Extending the Base Class
-------------------------

When you extend from the Solar_Base class, make sure the only constructor
parameter is `$config = null` (this is how it receives instantiation-time
configuration values) and that it calls the parent constructor at some point
(with the $config parameter passed up the chain).

For example:

{{code: php
    class Solar_Example extends Solar_Base {
        
        // default config values
        protected $_Solar_Example = array(
            'opt_1' => 'foo',
            'opt_2' => 'bar',
            'opt_3' => 'baz'
        );
        
        // constructor
        public function __construct($config = null)
        {
            // pre-parent setup code
            // ...
        
            // parent construction
            parent::__construct($config);
        
            // post-parent setup
            // ...
        }
    }
}}


Config File Settings
====================

Now, if your config file has an 'Solar_Example' group in it, those values will
override any of the default values set by your class definition. Say your
config file looks something like this:

{{code: php
    $config = array();
    // ...
    $config['Solar_Example']['opt_3'] = 'dib';
    // ...
    return $config;
}}

When you instantiate the Solar_Example object, the config file values will
override the default values, leaving all others in place:

{{code: php
    $example = Solar::factory('Solar_Example');
    /*
      The values of $example->_config are now:
  
      'opt_1' => 'foo'
      'opt_2' => 'bar'
      'opt_3' => 'dib' // from the config file
    */
}}

Instantiation Settings
======================

Finally, if you specify a configuration array as the second parameter of
[[Solar::factory()]], those values override both the default values of the
class definition and the Solar.config.php values.

{{code: php
    $config = array('opt_2' => 'gir');
    $example = Solar::factory('Solar_Example', $config);
    /*
      The values of $example->_config are now:
  
      'opt_1' => 'foo' // as defined by the class
      'opt_2' => 'gir' // from the Solar::factory() instantiation config
      'opt_3' => 'dib' // from the config file
    */
}}

Order of Precedence
===================

All of this is to say that the order of precedence for config values looks like this:

* The values start as defined by the class,

* And are overwritten by any config file values,

* And are again overwritten by values set at instantiation time

Note that values not changed remain the same, so if you leave one out, it's not overwritten to be null.
</markdown>