The aim of this page is to explain the basic concepts and terminology of CSF, to aid the understanding of the rest of the documentation and the correct usage of the framework.

As far as CSF is concerned, a library is just a PHP file it can include from within a registered library path. This file might contain the entire contents of a library, or it might include other files, or load other libraries—there are no restrictions. CSF maintains the state necessary to prevent double-loading of libraries. For example:

// Will include csf/libraries/csf_request.php
CSF::load_library('csf_request');
// Does nothing
CSF::load_library('csf_request');

Library path handling is intentionally “dumb”. If you want to group files together in subdirectories (e.g. for large, multi-file libraries):

// Attempts to load <librarypath>/foo/bar.php
CSF::load_library('foo/bar');

You can even use relative directory references (. and ..), but it's probably not a good idea for readability's sake.

Modules are essentially objects that you want global or centralised access to. An example is a database object that several parts of your application code all depend on. A module file is a PHP file which creates one or more of these objects and registers them into CSF. The file to include is determined using the same method as for libraries.

Module loading is a deliberately “hands off” procedure; the module name and configuration are exposed to the module file and it's the responsibility of that file to actually create and register the object(s). To use the example of the supplied “request” module, a module file might look like this:

CSF::load_library('csf_request');
CSF::register($MODULE_NAME, new csfRequest($MODULE_CONF));

Modules can be loaded in a few ways:

// Simplest example - default name, default configuration
CSF::load_module('request');
// Use a different name for the module
CSF::load_module(array('req', 'request'));
// Override the configuration
CSF::load_module('request', array('fix_magic_quotes' => false));

If no configuration is supplied when loading a module, it attempts to use CSF::config('modules.module_name') before defaulting to an empty array. (See the “Configuration” section for an explanation of CSF::config.)

There are a few different ways of accessing modules:

// The non-shortcut way
$m1 = CSF::get('module');
// Using the CSF() shortcut function
$m2 = CSF('module');
// Using a dummy csfModule instance
$csf = CSF();
$m3 = $csf->module;
// From inside the method of a class extending from csfModule
$m4 = $this->module;

Of course you don't need to assign the modules to variables before you use them, you can just chain calls like this:

$x = CSF('module')->method();

CSF uses a mechanism fairly similar to the PATH variable in most operating systems when searching for files, with the caveat that the most recently added paths are tried first. There are two collections of paths, one for libraries and one for modules, and they can be added to using CSF::add_library_path($path) and CSF::add_module_path($path) respectively. The first (lowest priority) paths are always libraries and modules under the directory that csf.php lives in.

The vast majority of web applications will want somewhere central to define configuration variables (e.g. a config.php) and preferably a nice way to get to them without resorting to globals. In CSF, this is simple:

// In config.php
$config['foo']['bar'] = 12;
$config['foo']['baz'] = false;
 
// When loading CSF
include 'config.php';
CSF::init($config);
 
// Somewhere else ...
$bar = CSF::config('foo.bar');     // $bar = 12
$foo = CSF::config('foo');         // $foo = array('bar' => 12, 'baz' => false)
$x = CSF::config('non.existant', 'defaultvalue');  // $x = 'defaultvalue'

CSF::init simply takes an array as input and stores it, and CSF::config uses a dot-separated path to traverse this array by key. This provides the ability to have a hierarchical configuration and a nice syntax for accessing the variables. If a second argument is provided to CSF::config, this is returned if the item isn't found, otherwise an exception is thrown.

Usually it's much nicer to be able to configure a framework in such a way that everything you want is loaded automatically, rather than having to write a load of boilerplate code. CSF provides it's autoloading mechanism in 3 parts:

• Add library and module paths, defined in the arrays at core.library_paths and core.module_paths
• Autoload libraries defined in an array of library names at autoload.libraries
• Autoload modules defined in an array of module names at autoload.modules - these are passed as the first argument to CSF::load_module, so can be (alias, module) pairs

Autoloading happens at the end of CSF::init, after configuration has been stored.