Last updated March 21, 2014. Created by irakli on March 7, 2010.
Edited by drupalshrek, tstoeckler, bleen18. Log in to edit this page.

Description

Libraries API addresses the problem of different modules including the same third-party library multiple times and accidentally creating version conflicts or double-inclusions errors. When modules use Libraries API (and the module) a library is downloaded once in sites/all/libraries (or site-specific libraries folder) much like a theme and all modules that need it can use the library from a central location.

Usage

  1. Come up with a sensible name for the library, one that most other module developers would use too. If some module already uses a library under a certain name, re-use that name. In most cases, the name is obvious, e.g. "ckeditor" for CKEditor javascript library, "spyc" for Spyc YAML parser library etc.
  2. In your module use libraries_get_path($name) to get the location of the library files. $name is the unique name of the library you chose in (1.). A common pattern is:
    if ($path = libraries_get_path($name)) {
      // Do something with the library, knowing the path, for instance:
      // drupal_add_js($path . '/example.js');
    }

    Note that with this example $path will have a value even if the library in question has not yet been downloaded. It will even have a value if the /sites/all/libraries folder does not yet exist.
  3. In the module installation instructions, instruct module users to download library under sites/all/libraries (or sites/sitename/libraries) within a folder named according to $library_name from (1). You can also include a Drush make file to let power-users download the library automatically.
  4. Make sure your module's .info file includes
    dependencies[] = libraries

That's it :)

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

Comments

Why the if in if ($path = libraries_get_path as libraries_get_path always returns something, even if the directory does not exist?

@bvanmeurs,

In this case, if the path does not exist, libraries_get_path will return FALSE. Unlike some languages, PHP evaluates assignment in an if statement by the vault that is assigned and not whether or not the value was successfully assigned. So in this case since $path now would be assigned FALSE, the if statement check fails and you do no perform the code inside the if statement. This is an easy way to combine steps so you don't have to write extra lines. The downside is that is may produce some confusing results if $path is used outside the if statement anywhere below.