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.

They open up security problems when register_globals is turned on.
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 Solar_Session storage object within your class. For example ...

<?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.

<?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 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 ...

<?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 ...

<?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.