Libraries API
Provides external library handling for Drupal modules, enabling version-dependent and shared usage of third-party JavaScript, CSS, and PHP libraries.
libraries
Install
composer require 'drupal/libraries:^4.1'
composer require 'drupal/libraries:^4.0'
Overview
Libraries API provides a unified, flexible framework for managing external (third-party) libraries in Drupal. It allows modules and themes to declare dependencies on external libraries and handles their detection, version checking, and loading automatically.
The module supports multiple library types including asset libraries (JavaScript and CSS files) that integrate with Drupal's core asset system, PHP file libraries for legacy code, and multiple asset libraries that contain several components. Libraries can be located via various methods including URI-based locators and global configuration.
Library definitions can be stored locally or fetched from remote registries like the Drupal Libraries Registry. The module provides version detection through pattern matching in library files, ensuring compatibility requirements are met. When enabled modules or themes declare library dependencies in their info files, Libraries API automatically registers the required external libraries with Drupal core's library system.
Features
- External library management system with plugin-based architecture for extensibility
- Support for asset libraries (JavaScript/CSS) that integrate with Drupal core's library attachment system
- Support for PHP file libraries that can be loaded on-demand
- Multiple asset library support for libraries containing several components
- Version detection through configurable detectors (line pattern matching, static version)
- Library locator plugins to find libraries in various filesystem locations
- Chain locator for trying multiple locations in sequence
- Global locator configuration via settings
- URI-based locator using stream wrappers (asset://, php-file://)
- Remote library definition fetching from registries like the Drupal Libraries Registry
- Local library definition storage with automatic caching
- Legacy API support (hook_libraries_info, libraries_load, libraries_get_path) for backward compatibility
- Declaration of library dependencies in module/theme info files using 'library_dependencies' key
- Drush integration for listing registered libraries and clearing library caches
- Stream wrappers for accessing library files (asset://, php-file://, library-definitions://)
Use Cases
Declaring Library Dependencies in a Module
Add a 'library_dependencies' key to your module's .info.yml file listing the machine names of required external libraries. Libraries API will automatically detect and register these libraries. Example: library_dependencies: ['flexslider', 'jquery_mobile']. The libraries will then be available for attachment via $element['#attached']['library'][] = 'libraries/flexslider'.
Creating a Library Definition File
Create a JSON file in public://library-definitions/ with the library's machine name (e.g., 'mylib.json'). Include type ('asset', 'php_file', or 'asset_multiple'), version_detector configuration, and file declarations. For asset libraries, specify 'css' and 'js' arrays following Drupal core's library structure. Example: {"type": "asset", "version_detector": {"id": "static", "configuration": {"version": "1.0"}}, "js": {"mylib.js": {}}, "css": {"base": {"mylib.css": {}}}}
Using the Library Manager Service
Inject or retrieve the 'libraries.manager' service to programmatically access library information. Use getLibrary($id) to get a library object with its detection status and metadata. Use load($id) for PHP file libraries to explicitly load their files. Use getRequiredLibraryIds() to get all libraries required by enabled extensions.
Implementing Custom Version Detection
For libraries with non-standard version formats, configure the 'line_pattern' version detector with a custom regex pattern, target file path, and line/column limits. In the library definition: {"version_detector": {"id": "line_pattern", "configuration": {"file": "CHANGELOG.md", "pattern": "/@version\s+([0-9.]+)/", "lines": 50}}}
Configuring Global Library Locations
Add global_locators to libraries.settings configuration to specify custom locations where libraries should be searched. Each locator is a plugin with ID and configuration. Example for a custom URI locator: global_locators: [{id: 'uri', configuration: {uri: 'public://custom-libraries'}}]
Using Legacy Libraries API
For backward compatibility, modules can still use libraries_load($name) to load a library, libraries_get_path($name) to get a library's filesystem path, and hook_libraries_info() to declare library information. These are deprecated but remain functional for migration purposes.
Tips
- Use the static version detector for libraries where the version cannot be programmatically detected, but only when you're certain about the installed version.
- The asset:// stream wrapper points to sites/all/assets/vendor by default - place asset libraries there for automatic discovery.
- The php-file:// stream wrapper points to sites/all/libraries by default - place PHP libraries there.
- Library definitions can use YAML format instead of JSON by overriding the libraries.definition.discovery service in your site's services.yml.
- For development, disable remote definition fetching (definition.remote.enable: false) to use only local definitions.
- When using Composer for PHP dependencies, prefer Composer's autoloading over Libraries API's php_file library type.
- Multiple variants of a library (e.g., minified vs source) can be declared in legacy hook_libraries_info() implementations.
- The chain locator allows trying multiple locations in priority order - useful for supporting various installation layouts.
Technical Details
Hooks 6
hook_libraries_library_type_info_alter
Allows modules to alter library type plugin information, such as changing the class used for a specific library type.
hook_libraries_locator_info_alter
Allows modules to alter library locator plugin information, enabling custom locator implementations.
hook_libraries_version_detector_info_alter
Allows modules to alter version detector plugin information for custom version detection logic.
hook_libraries_info
(DEPRECATED) Returns information about external libraries. Use library definition files instead. Will be removed before a stable release.
hook_libraries_info_alter
(DEPRECATED) Alters library information before detection and caching. Useful for adding integration files to libraries.
hook_libraries_info_file_paths
(DEPRECATED) Specifies additional paths to look for library info files. Use for modules declaring many libraries.
Drush Commands 2
drush libraries-list
Lists all registered libraries with their status (OK or error type), version, installed variants, and dependencies. Useful for debugging library installation issues.
drush cache-clear libraries
Clears the library cache, forcing re-detection of library installation status and versions on next access.
Troubleshooting 5
Verify the library is placed in a supported directory (libraries/, sites/all/libraries/, or profile's libraries/ directory). Check that the directory name matches the library's machine name. Use 'drush libraries-list' to check detection status. Ensure proper file permissions allow PHP to read the library files.
Check the version_detector configuration in the library definition. For line_pattern detector, verify the file path is correct relative to the library root, the regex pattern matches the version format in the file, and the lines/columns limits are sufficient to reach the version string.
Clear the library cache using 'drush cc libraries' or 'drush cache-clear libraries'. Library detection results are cached and won't update automatically when library files change.
Check that definition.remote.enable is TRUE in configuration. Verify the remote registry URLs are accessible. Check for network/firewall issues. The public://library-definitions directory must be writable for storing fetched definitions.
Ensure the library is listed in your module/theme's 'library_dependencies' in the info.yml file, or that another enabled extension declares it. Libraries API only registers libraries that are required by enabled extensions. Clear all caches after adding dependencies.
Security Notes 3
- Libraries API loads and executes PHP files from configured library directories. Ensure these directories are not writable by untrusted users.
- Remote library definition fetching uses HTTP by default (not HTTPS) for the default registry URL. Consider using HTTPS registry URLs in production.
- Library files are loaded from local filesystem paths. Ensure proper server configuration to prevent directory traversal or symlink attacks.