Libraries

What is a library?

Libraries are similar to classes and provide additional functionality for the software. The differences are that libraries are initialized manually within a controller and their methods do not have to be static.

Creating libraries

In order to function, a class must do the following:

  • Reside in “application/libraries” folder (or a sub-folder).
  • File name must match the class name exactly, e.g. email.php
  • The class name must map to the file name (with / replaced with _) and each word is capitalized.
  • Must have the Library class as a (grand)parent.

Some examples of library names and file locations:

// application/libraries/email.php
class Email extends Library {
 
// application/libraries/storage.php
class Storage extends Library {

Libraries can be in sub-folders:

// application/libraries/foo/bar.php
class Foo_Bar extends Library {
 
// application/libraries/storage/files.php
class Storage_Files extends Library {

Libraries can extend other libraries:

// application/libraries/files.php
class Files extends Storage {
 
// application/libraries/products.php
class Products extends Store {

Loading libraries

Libraries will typically be loaded and called from within your controller functions. To load a library you will use the following function:

loader::library('email');

You may now access its methods in the controller like this:

$this->email->send();

You may pass additional variables to the library’s constructor if necessary when loading it:

class Email extends Library
{
	private $config = array();
	public function __construct($config = array())
	{
		parent::__construct();
		$this->config = $config;
	}
}
// In the controller we'd have this:
loader::library('email', array('config' => $config));

You may also assign a different name for it to be used in controller:

loader::library('email', array(), 'my_email');
$this->my_email->send();

You may also assign your library class directly to a variable:

$email = loader::library('email', array(), null);
$email->send();

If your library is located in a sub-folder then upon loading it system would use the file name of the library by default as its name. For example this library:

// application/libraries/storage/files.php
class Storage_Files extends Library {

Upon loading it, we’ll be able to refer to it like this:

loader::library('storage/files');
$this->files->write();

You may always specify the name manually if you prefer:

loader::library('storage/files', array(), 'my_files');
$this->my_files->write();

Core libraries

There are several core libraries that are included as part of the core framework. These libraries are located in the “system/libraries” folder. They can be accessed the same way as in the examples above.

Extending core libraries

It is possible to extend core libraries by creating files with the same name and placing them in the “application/libraries” folder. For example to extend “Email” class, we would create a file called “email.php” in that folder and place the following code in it (notice the name of the library we extend):

class Email extends CodeBreeder_Email
{
	public function my_method()
	{
		echo "example method";
	}
}