public static method

Adds a class library from which files can be loaded.

The add() method registers a named library configuration to your application, and is used to allow the framework to auto-load classes on an as-needed basis.

Adding libraries to your application

In Lithium, libraries represent the broadest unit of class organization in an application, and everything is a library; this includes your application, and the Lithium framework itself. Libraries can also be other frameworks, like Solar, Zend Framework or PEAR, or Lithium plugins, which are simply libraries that follow the same organizational standards as Lithium applications.

By convention, libraries are placed in the libraries directory inside your application, or the root libraries directory at the top level of the default distribution (i.e. the one that contains the lithium directory), however, you can change this on a case-by-case basis using the 'path' key to specify an absolute path to the library's directory.


  • string $name

    Library name, i.e. 'app', 'lithium', 'pear' or 'aura'.

  • array $config

    Specifies where the library is in the filesystem, and how classes should be loaded from it. Allowed keys are:

    • 'bootstrap' mixed: A file path (relative to 'path') to a bootstrap script that should be run when the library is added, or true to use the default bootstrap path, i.e. config/bootstrap.php.
    • 'defer' boolean: If true, indicates that, when locating classes, this library should defer to other libraries in order of preference.
    • 'includePath' mixed: If true, appends the absolutely-resolved value of 'path' to the PHP include path. If a string, the value is appended to PHP's.
    • 'loader': An auto-loader method associated with the library, if any.
    • 'path': The directory containing the library.
    • 'prefix' string: The class prefix this library uses, i.e. 'lithium\', 'Zend_' or 'Solar_'. If the library has no global prefix, set to false.
    • 'suffix' string: Gets appended to the end of the file name. For example, most libraries end classes in '.php', but some use '.class.php', or '.inc.php'.
    • 'transform' \Closure: Defines a custom way to transform a class name into its corresponding file path. Accepts either an array of two strings which are interpreted as the pattern and replacement for a regex, or an anonymous function, which receives the class name and library configuration arrays as parameters, and returns the full physical file path as output.
    • 'resources' string: If this is the default library, this maybe set to the absolute path to the write-enabled application resources directory, which is used for caching, log files, uploads, etc.



Returns the resulting set of options created for this library.


	public static function add($name, array $config = []) {
		$defaults = [
			'name' => $name,
			'path' => null,
			'prefix' => $name . "\\",
			'suffix' => '.php',
			'loader' => null,
			'includePath' => false,
			'transform' => null,
			'bootstrap' => true,
			'defer' => false,
			'default' => false
		if ($name === 'lithium') {
			$defaults['defer'] = true;
			$defaults['bootstrap'] = false;
			$defaults['path'] = dirname(__DIR__);
			$defaults['loader'] = 'lithium\core\Libraries::load';
		if (isset($config['default']) && $config['default']) {
			static::$_default = $name;
			$defaults['path'] = LITHIUM_APP_PATH;
			$defaults['bootstrap'] = false;
			$defaults['resources'] = LITHIUM_APP_PATH . '/resources';
		$config += $defaults;

		if (!$config['path']) {
			if (!$config['path'] = static::_locatePath('libraries', compact('name'))) {
				throw new ConfigException("Library `{$name}` not found.");
		$config['path'] = str_replace('\\', '/', $config['path']);
		static::_configure(static::$_configurations[$name] = $config);
		return $config;