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

This documentation is aimed at module maintainers and developers who want to leverage Libraries API within their own extensions.

Why Use Libraries API in Drupal 8?

Drupal 8 core has introduced improved library management tools (libraries.yml and unified library loading) leaving some to wonder why the Libraries API module is still needed. Despite these changes core still does not offer a solution for handling external library dependencies that may be shared across multiple extensions, which is the main problem space the Libraries API project continues to focus on. Any projects that depend on external and/or shared libraries can benefit from several important advantages Libraries API provides, including:

1. Avoiding load conflicts. Drupal 8 core does not offer a way for common library dependencies (e.g. a commonly used javascript library) to be declared canonically. If multiple extensions declare the same dependency via core's APIs alone a variety of conflicts can occur (version issues, double-inclusion errors, etc.). Libraries API provides a central framework to avoid these problems while leveraging Drupal core's native APIs for actual library loading.
2. Centralized maintenance of library metadata. Unlike the Drupal 7 versions of Libraries API, library metadata is now decoupled from the extensions that use it. This metadata (previously defined in hook_libraries_info()) is instead read from a common shared registry that can be accessed remotely and transparently. This will provide numerous advantages including greater consistency for site builders using different versions of library-dependent modules.
3. An extended API and toolkit for developers. Tools for version detection, configurable management of library sources and other benefits that have always been part of the Libraries API project are still available and do not need to be duplicated.

Libraries API 3.x uses core's asset management APIs directly by registering asset libraries on behalf of other extensions. This means that, despite the project name, developers do not have to learn a whole new API to take advantage of these benefits.

Historical note: Many of the background notes used to explain the philosophy of the 7.x-2.x version also apply to 8.x-3.x.

Note on PHP libraries: With Drupal 8 relying on Composer for autoloading and dependency resolution of PHP libraries, asset libraries are the primary use-case for Libraries API, though basic support for management and loading of PHP libraries is still included.

Library Definitions

In order to be useful to other modules Libraries API needs a list of known libraries and basic metadata about each. In Drupal 7 library information could be provided by module-independent info files, but as noted above this causes numerous inconsistencies. In 8.x-3.x library metadata is managed separately as portable JSON files that can be accessed from numerous locations. The API natively makes use of two "registry" locations for these definitions:

• The remote registry (default URL: https://git.drupalcode.org/project/libraries_registry/tree/8.x-1.x/registry/8) is a "master" source of library definitions that are shared across multiple Drupal instances, and typically accessed via http. The Libraries Registry project is an effort to provide a shared remote registry for the Drupal community. It is also the remote registry that Libraries API is setup to use out-of-the box, though this can be customized (any URI can be referenced, and multiple remote registries can be declared).
• The local registry (default URI: public://library-definitions/, typically at /sites/all/files/library-definitions/) is instance-specific local file storage for all library definitions needed by a specific site. This is the primary source of all library metadata during any run-time operations. When a definition is needed (e.g. a module using Libraries API is installed or a new library is being loaded for the first time) the remote registry is checked, and if the definition is found, it is copied to this local registry for ongoing reference.

Though the default local and remote registry settings will be sufficient for most cases, and transparent to most site builders, additional registry locations and custom discovery logic can be added (see the Advanced API docs for more).

If your extension depends on an external library you will first need to ensure that the library has a definition file available. If a definition file already exists in the Libraries Registry project, and it does not need to be modified, then there is nothing special that you have to do. In this case libraries API will fetch the needed definition automatically within your development environments and any other environments running your extension.

If a definition file does not already exist, or the one available in the Libraries Registry project requires modification, you will need to create a new definition file. Please reference the library definition structure for specifics on this. You can manually place this definition inside the local registry (typically in /sites/all/files/library-definitions/) on any development instances you are working with for immediate use. Once the definition file is finalized and you are ready to share your extension (e.g. as a release on drupal.org) it's best to submit it back to the the Libraries Registry project for universal remote access across all sites that will be using your extension.

Usage

Once definitions exists for your external library dependencies, and are available in the appropriate registry, using the API should be fairly straightforward.

Basic setup

First you will need to declare a dependency on Libraries API in your module or theme's info.yml file:

dependencies:
  - libraries

The actual external library dependences must also be declared in the info.yml file using the "library_dependencies" key and a sequence of library machine names, such as:

library_dependencies:
  - flexslider
  - jquery_mobile

You should instruct your users to place the external library sources in a location within their local Drupal file structure that Libraries API is aware of, typically /sites/all/assets/vendor/[lib_machine_name] (for asset libraries) or /sites/all/libraries/[lib_machine_name] (for PHP libraries). You can add notes about this to your module's documentation or simply direct users to the Installing an external library that is required by a contributed module page of the Libraries API documentation. Of course, you will also need to ensure that library sources are appropriately located on any development environments that you are using.

Library loading - Attaching asset libraries

Libraries API uses core's library handling concepts directly for loading/attaching asset libraries. This means that all of the attaching notes from the core documentation apply directly. For example to load a library via the #attached property of a render array you can use:

$build['the_element_that_needs_the_asset_library']['#attached']['library'][] = 'libraries/flexslider';

Important note: The attached value should always use "libraries" as the module label (i.e. libraries/lib_machine_name as opposed to mymodule/lib_machine_name). This is because the external library has been registered canonically via libraries API on behalf of your module and all other modules that may also use the same library.

Library loading - Including PHP libraries

For feature parity with the Drupal 7 version of this module basic PHP library support is available to load a list of PHP files on demand. Generally, it is encouraged to use Composer and avoid Libraries API altogether for PHP libraries, but for cases where Composer-based management is not possible PHP libraries can be included via the library manager service. Simply calling \Drupal\libraries\ExternalLibrary\LibraryManagerInterface::load() will include all files that are defined as part of a PHP library, for example:

\Drupal::service('libraries.manager')->load('php_library_machine_name');

Detecting a library version programmatically

Notes needed