Last updated March 21, 2014. Created by tstoeckler on November 15, 2011.
Edited by drupalshrek, clement.ferrier, thisliquidspace, JeremyFrench. Log in to edit this page.

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 either by implementing 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()

<?php
/**
* 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'),
    ),
  );
  return
$libraries;
}
?>

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 a 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!

Loading

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

<?php
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:
<?php
// Try to load the library and check if that worked.
if (($library = libraries_load($name)) && !empty($library['loaded'])) {
 
// Do something with the library here.
}
?>

Detection

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

<?php
$library
= libraries_detect($name);
?>

Similar to checking whether the library was loaded above, we can then check if the library is installed:
<?php
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'];
}
?>

You can also attach library to renderable array like that

<?php
$form
['myelement']['#attached']['libraries_load'][] = array('myAwesomeLibrary');
?>

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

Just wanted to throw it out there... that this is confusing and in trying to work with this libraries module, it's turned a very very stupid simple module into a headache to configure, and not nearly as simple to hand off.

How the heck do you write a .info file for a JS library.

EDIT: removed a more lengthy response since it's already answered better on the other pages related to this module.

In short; You don't have to write a .info file for a library if you don't want to. Just implement hook_libraries_info() in a small Drupal module by following the examples in libraries.api.php. That way is currently better documented. Need help with the rest, file a support request in the issue queue and ask them to update the docs as well.

While it's possible to specify different versions and variants of those versions of external libraries, damned if I can figure out how you actually load a SPECIFIC version of a libary (and, of course, variant within that version).

So, how is that done?

And how in the world do you use the callbacks?

I've spent a few days pouring over the libraries code itself trying to figure this out with no joy.

Any help would be appreciated.

Best,

Dick Munroe

Richard Munroe
Cottage Software Works, Inc.
Our Motto: Cottage Software Works!

You could use libraries_detect() to check the current installed version and see if there's the variant and version you need.

Actually, the bundles libraries.api.php file says that only one version can be installed and used per site, since it will always get the same library name.
You can only detect the version that is installed so your module can cope with that version.
So I don't think you can load specific versions, you can only detect the version, then use the version info to adapt your module.

Found this in libraries.api.php of the libraries package line 31.

Wakken!

Since the libraries info data is cached, remember to clear the cache everytime you change your hook_libraries_info() data. That'll save you some headaches.