Using Libraries API 2.x (as a module-developer)

See also: The ideas and design behind Libraries API 2.x

Declaration

Libraries API 2.x includes a library registry, so if you want to use an external library in your module, you need to make it known first. You can do this by implementing either hook_libraries_info() in your module or by providing an info file for your library, which users then have to download.

Using hook_libraries_info()

/**
 * Implements hook_libraries_info().
 *
 * For defining external libraries.
 */

function simple_libraries_info() {

  // A very simple library. No changing APIs (hence, no versions), no variants.
  // Expected to be extracted into 'sites/all/libraries/simple'.
  $libraries['simple'] = array(
    'name' => 'Simple library',
    'vendor url' => 'http://example.com/simple',
    'download url' => 'http://example.com/simple',
    'version arguments' => array(
      'file' => 'simple.js', // Could be any file with version info 
      'pattern' => '/Version (\d+)/', 
      'lines' => 5,
    ),
    'files' => array(
      'js' => array('simple.js'), //this can be a path to the file location like array('lib/simple.js')
    ),
  );

  return $libraries;
}

Version detection

Version detection is using regular expressions. If you'd like to bypass the version detection regex you can replace the "version arguments" array with a callback as demonstrated below:

  $libraries['simple'] = array(
    'name' => 'Simple library',
    'vendor url' => 'http://example.com/simple',
    'download url' => 'http://example.com/simple',
    'version callback' => 'simple_version_callback',
    'files' => array(
      'js' => array('simple.js'), //this can be a path to the file location like array('lib/simple.js')
    ),
  );

function simple_version_callback() {
  //use some fancy magic to get the version number... or don't
  return TRUE;
}

Using an .info file

The info file should be in the same format as a regular Drupal info file for a module or theme, and should contain exactly the same keys that are described in hook_libraries_info().

name = CustomLibrary
machine name = CustomLibrary
description = Provides an interface to the CustomLibrary
version = 1
files[php][] = customlibrary.inc.php

Required information are name, machine name, version and files. This info file must be placed in the top level library directory, e.g. sites/all/libraries. In this example the file customlibrary.inc.php will need to be in sites/all/libraries/CustomLibrary/. The info file must be entirely lowercased, otherwise it will not be found.

The info file must be named $name.libraries.info (where $name is the machine name of the library) and placed in the top level of one of the libraries directories (e.g. sites/all/libraries).

When choosing the internal name ("machine name", will be $name below) of your library, please check for other libraries or Drupal modules with the same name first.

If you have Drush installed, you can see whether Libraries API found your library information by running drush libraries-list in the context of your Drupal site. Otherwise, you can check the output of libraries_info($name).

If Libraries API has found your library, you're ready to use the library in your module!

Load library

To load the library from inside your module, simply do:

libraries_load($name);

Usually, you'll want to do something after the library has been loaded. Because you cannot always depend on the library being installed you have to check first if the loading was actually successful:

// Try to load the library and check if that worked.
if (($library = libraries_load($name)) && !empty($library['loaded'])) {
  // Do something with the library here.
}

Check existence

If you just want to check whether the library is installed, but don't want to load it right away, you can use:

$library = libraries_detect($name);

Similar to checking whether the library was loaded above, we can then check if the library is installed:

if (($library = libraries_detect($name)) && !empty($library['installed'])) {
  // The library is installed. Awesome!
}
else {
  // Something went wrong. :(
  // This contains a short status code of what went wrong, such as 'not found'.
  $error = $library['error'];
  // This contains a detailed (localized) error message.
  $error_message = $library['error message'];
}

Render arrays & Form API

You can also attach library to renderable array like that

$form['myelement']['#attached']['libraries_load'][] = array('myAwesomeLibrary');