<markdown>
==================
Naming Conventions
==================


-----------
Class Names
-----------

All Solar class names start with `Solar_` and map directly to their filesystem
location, where the underscore maps to a slash (i.e., a sub-directory).

For example, the `Solar_Auth_Adapter_Sql` class is located at
`Solar/Auth/Adapter/Sql.php`.

This makes it possible to use [[Solar::autoload()]] and [[Solar::factory()]]
to automatically load and configure new instances.


------------
Method Names
------------

When reasonable, methods in Solar classes conform to these names when
they perform these related functions:

| Method Name  | Usage                                                                                                      | Examples 
| ------------ | ---------------------------------------------------------------------------------------------------------- | --------
| `delete`     | deletes data from storage (instead of remove/destroy)                                                      | `$table->delete($where)`
| `fetchAllBy` | returns multiple entries from storage, using alternative or additional criteria                            | `$table->fetchAllByName($name)`
| `fetchAll`   | returns multiple entries from storage                                                                      | `$table->fetchAll()`
| `fetchBy`    | returns one entry from storage, using alternative or additional criteria (instead of fetchWith/fetchFor)   | `$table->fetchByName($name)`
| `fetch`      | returns one entry from storage (instead of get/find/retrieve)                                              | `$cache->fetch($id)`
| `get`        | gets the value of a property                                                                               | `$obj->getProperty()`
| `insert`     | inserts new data in storage (instead of add/new/save)                                                      | `$table->insert($data)`
| `is`         | the method returns boolean true/false                                                                      | `$cache->isActive()`
| `load`       | loads property values from an external source                                                              | `$role->load($handle)`
| `sanitize`   | **forces** a value to match a known format                                                                 | `$filter->sanitizeFloat($value)`
| `save`       | updates existing data **or** inserts new data in storage (instead of replace)                              | `$cache->save($id, $data)`
| `set`        | sets the value of a property                                                                               | `$obj->setProperty($value)`
| `update`     | updates existing data in storage (instead of save/change)                                                  | `$table->update($data, $where)`
| `validate`   | checks that a value matches a known format, returns boolean true/false                                     | `$filter->validateFloat($value)`


These names are not set in stone, but are used when reasonable.


----------------
Global Variables
----------------

Solar does not use global variables.

1. They open up security problems when `register_globals` is turned on.

2. They pollute the global namespace and may collide or overwrite each other
   in differing contexts.

-----------------
Session Variables
-----------------

`$_SESSION` keys for Solar classes match the class name. Thus, a
`Solar_Example` class using a session variable called `foo` would be addressed
as `$_SESSION['Solar_Example']['foo']`.

The easiest way to adhere to this convention is to use a [[Class::Solar_Session| ]]
storage object within your class. For example ...

{{code: php
    $session = Solar::factory('Solar_Session',
        array('class' => 'Solar_Example')
    );

    // equivalent of $_SESSION['Solar_Example']['something']
    $session->store['foo'] = 'bar';
}}


--------------------
Config File Keys
--------------------

Keys in the [[config file]] conform to the class name. Thus, a `Solar_Example`
constructor configuration is addressed as an associative array in the
`['Solar_Example']` key of the [[config file]].

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


------------
Locale Files
------------

[[Locale files]] are named for their locale code. For example, the `en_US`
file is named `en_US.php`, the `pt_BR` file is named `pt_BR.php`, and so on.

[[Locale files]] are placed in a subdirectory of the class; the subdirectory
is always named `Locale`. For example, locale files for the `Solar_Test` class
are located at `Solar/Test/Locale/*`.

    Solar/
        Example.php
        Example/
            Locale/
                en_US.php
                pt_BR.php


-----------------------
Locale Translation Keys
-----------------------

Keys in the [[locale files]] are usually in all capitals, using only A-Z, 0-9,
and underscores for the key name. In general, we prefix the key name with a
hint for its usage:

|  Prefix    | Usage
| ---------- | -------------------------------------------------------------------
| `ACTION_`  | Displayed text for page-controller action names
| `DESCR_`   | Form element descriptions (long text)
| `ERR_`     | Logic error and exception messages
| `FAILURE_` | Failure messages, typically form-related
| `FORMAT_`  | Formatting strings for the locale
| `HEADING_` | Heading titles
| `INVALID_` | Invalid data message
| `LABEL_`   | Form element labels (short text)
| `LEGEND_`  | Fieldset legend titles
| `SUCCESS_` | Success messages, typically form-related
| `PROCESS_` | Displayed text for action processes, typically submit-button values
| `TEXT_`    | General-purpose text
| `WARNING_` | Warnings, typically form-related


---------------
Exception Names
---------------

Exceptions related to a particular class are always named for that class.
Generic exceptions use an `_Exception` name suffix, and specific exceptions
add a single string after that.

For example, a generic example exception would be `Solar_Example_Exception`,
while related FooBar and BazDib exceptions would be named
`Solar_Example_Exception_FooBar` and `Solar_Example_Exception_BazDib`,
respectively.

    Solar/
        Example.php
        Example/
            Exception.php
            Exception/
                FooBar.php
                BazDib.php

Classes descended from [[Class::Solar_Base | ]] automatically convert specific
error codes into exception class names, and then attempt to use a related
locale string for the exception message.

For example, if you have this in your locale file ...

{{code: php
    return array (
        'ERR_FOO_BAR' => "A foo-bar exception occurred.",
        'ERR_BAZ_DIB' => "Baz-dib was raised, you should look into it.",
    );
}}

... and you throw an exception using [[Solar_Base::_exception()]] like so ...

{{code: php
    class Solar_Example extends Solar_Base {
        function kaboom()
        {
            throw $this->_exception('ERR_FOO_BAR');
        }
    }
}}

... then Solar automatically finds the Solar_Example_Exception_FooBar class
and throws it, using the localized ERR_FOO_BAR message.
</markdown>