The ideas and design behind Libraries API 2.x

WARNING: Not only is this document incomplete, but the APIs it is trying to document are still in flux and subject to change. Rather than concrete API documentation, this is meant to be an explanation of the larger design choices behind Libraries API 2.x.

The following are things we've learned and choices we've made, each with a detailed reasoning and effects this decision had. Please do comment here or open an issue in the Libraries API issue queue, if you find a flaw with anything mentioned here.

Overview

• External libraries should not be committed to the source code on drupal.org
• Libraries should not reside in module folders
• Libraries API needs to be able to detect a library's version
• Only one version of a library can be installed per site
• Libraries API needs meta information about libraries

External libraries should not be committed to the source code on drupal.org

Reasoning

• We have a strict GPLv2+ policy for the drupal.org contributions repository, which conflicts with certain libraries.
• Modules and themes on drupal.org and their release cycles should not be affected by the release cycles of external libraries.

Effect

Libraries need to be obtained separately from Drupal modules and themes. For now this has to be done manually. For developers, work is going on to utilize Drush make. For Drupal 7, the upgrade manager might be utilized in the future.

Libraries should not reside in module folders

Reasoning

• Best practices for module upgrades dictate to delete the old module folder before the upgrade. This removes any libraries inside of that folder.
• Multiple modules can implement the same library.

Effect

The best practice is to place libraries into a sites/all/libraries directory. All possible locations are:

sites

Similar to how core module and themes are in a top-level modules resp. themes directory. To be used for distributions, who want to make the libraries available for all sites and all profiles.

profiles/$profilename/libraries

Similar to profile-specific modules and themes, libraries can also be profile-specific.

sites/all/libraries

To be used for multi-site installations, if a library is to be available to all sites. This is the default location that should be used in most cases.

sites/$sitename/libraries

In multi-site installations for libraries that are site-specific.

The fact that the location of the library is not known upfront is one of the essential differences to hook_library() provided by core in Drupal 7.

Libraries API needs to be able to detect a library's version

Reasoning

Release cycles of Drupal modules and themes can be different than the release cycles of external libraries. That means, Libraries API and no other Drupal module has control over which version of a library is installed.

Effect

Libraries API supports version detection of libraries and provides a library's version information to modules. Modules implementing libraries can provide version-specific integration code or at least bail out in case of incompatible versions.
The current code flow is:

$library = libraries_detect('example_library');
$version = $library['version'];

This allows different versions of the same library to be supported. This is one of the essential differences to hook_library() provided by core in Drupal 7.

Only one version of a library can be installed per site

Reasoning

If two different versions of the same library are installed, there is no way to guarantee that they will not both be loaded on the same page. If that were the case, visual errors could appear in case of CSS libraries, functional errors in case of JavaScript libraries and fatal errors in case of PHP libraries.

Libraries API needs meta information about libraries

• A Drupal-specific "machine name" for Libraries API and other modules to reference the library by.
• Name, Website and Download link for the (yet to come) Libraries API user interface.
• Information how to detect the version of the library (see above)
• Files that belong to this library. Note that since this information can vary between library versions. Also some libraries come with different 'variants'. For example a 'source code variant' and a 'minified variant'. Or TinyMCE, for instance, comes with a special 'jQuery-based variant'.
• Module's and theme's integration files to load alongside the library.
• Library dependencies. (not yet supported)

See the API documentation for hook_libraries_info() for a detailed explanation of the information currently needed.
There are currently two ways to declare this information:

• Implementing hook_libraries_info() in a module
• Providing an info file for the library. The info file should 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).