This is a master issue to track progress of the 8.x-3.x release of Libraries API. This will be a completely revamped release. As in Drupal 7 Libraries API remains an important requirement for D8 sites and overall CX. Though Drupal 8 core has introduced improved library management tools (libraries.yml and unified library loading) it still does not offer a solution for handling external library dependencies that may be shared across multiple extensions. As a result this remains the primary problem space for the Libraries API module.
How to Use the New API
The main concepts and terminology of the new API are documented in libraries.api.php. This is required reading for the following. Please do comment below if things there are lacking/missing/incorrect so we can improve it. That way the best documentation will be available to anyone installing Libraries API without having to dig through the issue queue.
The following will be an explanation of how a module (or theme) in Drupal 8 can attach/load an external library and what happens behind the scenes to achieve that with links to issues where functionality is missing or lacking.
- Declare a dependency on the library in the
- The syntax for declaring library dependencies is as documented in libraries.api.php:
name: My module type: module core: 8.x library_dependencies: - flexslider - jquery_mobile
Libraries API will validate that information when the module is installed ():
- It checks whether we have a library definition by that name on the library registry ( )
- If not it aborts installation. If so, it downloads the library definition
- If the library has dependencies it goes through this whole process for those
- If the library requires installation (that is not always the case) it will try to install it
(If either the library definition is already there or the library is already installed it skips the respective steps, of course.)
- Use the library using just its name
- For asset libraries:
Libraries API registers all external asset libraries that are dependencies of modules with the core library system. Thus, given the above example module info file, the Flexslider library can be attached to a render array as documented in AssetLibraryInterface:
$build['#attached']['library'] = ['libraries/flexslider'];
For PHP file libraries:
PHP file libraries can be loaded in an ad-hoc fashion by calling
- Versioned metadata
- Drupal 7 Libraries API has a
versionskey, which - albeit there being some issues with the specific implementation - we conceptually need to bring into the Drupal 8 version. The idea is that library metadata can change between versions, i.e. libraries can rename files or change their version detection scheme and we need to cope with that. No issue for this yet.
- Loading of minified assets
- Drupal 7 Libraries API has the concept of
variantswhich allows libraries to specify a source and a
minifiedvariant. The problematic part about the Drupal 7 implementation is that modules have to specify which variant to load themselves. We should handle this generically and simply put a checkbox on
/admin/config/development/performanceand then load either source or minified assets for all external libraries that support this.
In addition to the issues linked above, some features are missing to provide a rich developer experience
Overall Architectural Considerations
- A remote central repository of library definitions managed by/for the Drupal community (see next section - #773508).
- Leveraging definition data from existing cloud services (cdnjs.com).
- A hybrid approach that allows use of remote definitions with the ability for local overrides.
The extent to which Libraries API can (or should) be a solution for non-asset libraries (beyond JS and CSS assets) is an open topic. If this continues to be a priority (do we need a simple y/n issue for that?) the following issues are potentially relevant:
- Libraries 7.x-2.x already supported 3 types of libraries (JS, CSS, PHP). We want to
- Support more library types (Autoload, PEAR, ...)
- Allow certain libraries to have their own business logic with regards to loading, etc.
Both of these points can be easily achieved in an object-oriented fashion. Since (a) we gain automatic autoloading of the Library information files and (b) Drupal 8 is moving towards an object-oriented design, this seems like a natural fit. We will organize both our own files, as well as the Library classes in accordance with PSR-0.
- Since http://packagist.org/, which uses Composer, seems to be the PHP package archive, we want to download all libraries (possibly even including JS and CSS libraries) from there. That means that if a certain library does not have a
composer.jsonfile, and/or a package on http://packagist.org/, this needs to added "upstream" first, in order for Libraries API to support it. Each Library class will include a method called "getComposerURL", which Libraries API will use to download the library.