Libraries API
Proporciona gestión de bibliotecas externas para módulos de Drupal, permitiendo el uso compartido y dependiente de versiones de bibliotecas JavaScript, CSS y PHP de terceros.
libraries
Install
composer require 'drupal/libraries:^4.1'
composer require 'drupal/libraries:^4.0'
Overview
Libraries API proporciona un marco de trabajo unificado y flexible para gestionar bibliotecas externas (de terceros) en Drupal. Permite que módulos y temas declaren dependencias de bibliotecas externas y gestiona automáticamente su detección, verificación de versiones y carga.
El módulo soporta múltiples tipos de bibliotecas incluyendo bibliotecas de assets (archivos JavaScript y CSS) que se integran con el sistema de assets del core de Drupal, bibliotecas de archivos PHP para código heredado, y bibliotecas de múltiples assets que contienen varios componentes. Las bibliotecas pueden localizarse mediante varios métodos incluyendo localizadores basados en URI y configuración global.
Las definiciones de bibliotecas pueden almacenarse localmente u obtenerse de registros remotos como el Drupal Libraries Registry. El módulo proporciona detección de versiones mediante coincidencia de patrones en archivos de biblioteca, asegurando que se cumplan los requisitos de compatibilidad. Cuando los módulos o temas habilitados declaran dependencias de bibliotecas en sus archivos info, Libraries API registra automáticamente las bibliotecas externas requeridas con el sistema de bibliotecas del core de Drupal.
Features
- Sistema de gestión de bibliotecas externas con arquitectura basada en plugins para extensibilidad
- Soporte para bibliotecas de assets (JavaScript/CSS) que se integran con el sistema de adjuntos de bibliotecas del core de Drupal
- Soporte para bibliotecas de archivos PHP que pueden cargarse bajo demanda
- Soporte para múltiples bibliotecas de assets para bibliotecas que contienen varios componentes
- Detección de versiones mediante detectores configurables (coincidencia de patrones de línea, versión estática)
- Plugins localizadores de bibliotecas para encontrar bibliotecas en varias ubicaciones del sistema de archivos
- Localizador en cadena para probar múltiples ubicaciones en secuencia
- Configuración global de localizadores mediante ajustes
- Localizador basado en URI usando stream wrappers (asset://, php-file://)
- Obtención remota de definiciones de bibliotecas desde registros como el Drupal Libraries Registry
- Almacenamiento local de definiciones de bibliotecas con caché automático
- Soporte de API heredada (hook_libraries_info, libraries_load, libraries_get_path) para compatibilidad retroactiva
- Declaración de dependencias de bibliotecas en archivos info de módulos/temas usando la clave 'library_dependencies'
- Integración con Drush para listar bibliotecas registradas y limpiar cachés de bibliotecas
- Stream wrappers para acceder a archivos de bibliotecas (asset://, php-file://, library-definitions://)
Use Cases
Declarar dependencias de bibliotecas en un módulo
Añade una clave 'library_dependencies' al archivo .info.yml de tu módulo listando los nombres de máquina de las bibliotecas externas requeridas. Libraries API detectará y registrará automáticamente estas bibliotecas. Ejemplo: library_dependencies: ['flexslider', 'jquery_mobile']. Las bibliotecas estarán entonces disponibles para adjuntar mediante $element['#attached']['library'][] = 'libraries/flexslider'.
Crear un archivo de definición de biblioteca
Crea un archivo JSON en public://library-definitions/ con el nombre de máquina de la biblioteca (ej., 'mylib.json'). Incluye type ('asset', 'php_file', o 'asset_multiple'), configuración de version_detector y declaraciones de archivos. Para bibliotecas de assets, especifica arrays 'css' y 'js' siguiendo la estructura de bibliotecas del core de Drupal. Ejemplo: {"type": "asset", "version_detector": {"id": "static", "configuration": {"version": "1.0"}}, "js": {"mylib.js": {}}, "css": {"base": {"mylib.css": {}}}}
Usar el servicio Library Manager
Inyecta u obtén el servicio 'libraries.manager' para acceder programáticamente a la información de bibliotecas. Usa getLibrary($id) para obtener un objeto de biblioteca con su estado de detección y metadatos. Usa load($id) para bibliotecas de archivos PHP para cargar explícitamente sus archivos. Usa getRequiredLibraryIds() para obtener todas las bibliotecas requeridas por las extensiones habilitadas.
Implementar detección de versiones personalizada
Para bibliotecas con formatos de versión no estándar, configura el detector de versiones 'line_pattern' con un patrón regex personalizado, ruta de archivo objetivo y límites de línea/columna. En la definición de biblioteca: {"version_detector": {"id": "line_pattern", "configuration": {"file": "CHANGELOG.md", "pattern": "/@version\\s+([0-9.]+)/", "lines": 50}}}
Configurar ubicaciones globales de bibliotecas
Añade global_locators a la configuración libraries.settings para especificar ubicaciones personalizadas donde se deben buscar las bibliotecas. Cada localizador es un plugin con ID y configuración. Ejemplo para un localizador URI personalizado: global_locators: [{id: 'uri', configuration: {uri: 'public://custom-libraries'}}]
Usar la API heredada de Libraries
Para compatibilidad retroactiva, los módulos aún pueden usar libraries_load($name) para cargar una biblioteca, libraries_get_path($name) para obtener la ruta del sistema de archivos de una biblioteca, y hook_libraries_info() para declarar información de bibliotecas. Estos están obsoletos pero permanecen funcionales para propósitos de migración.
Tips
- Usa el detector de versiones static para bibliotecas donde la versión no puede detectarse programáticamente, pero solo cuando estés seguro de la versión instalada.
- El stream wrapper asset:// apunta a sites/all/assets/vendor por defecto - coloca las bibliotecas de assets ahí para descubrimiento automático.
- El stream wrapper php-file:// apunta a sites/all/libraries por defecto - coloca las bibliotecas PHP ahí.
- Las definiciones de bibliotecas pueden usar formato YAML en lugar de JSON sobrescribiendo el servicio libraries.definition.discovery en el services.yml de tu sitio.
- Para desarrollo, deshabilita la obtención de definiciones remotas (definition.remote.enable: false) para usar solo definiciones locales.
- Cuando uses Composer para dependencias PHP, prefiere el autoloading de Composer sobre el tipo de biblioteca php_file de Libraries API.
- Múltiples variantes de una biblioteca (ej., minificada vs fuente) pueden declararse en implementaciones heredadas de hook_libraries_info().
- El localizador chain permite probar múltiples ubicaciones en orden de prioridad - útil para soportar varios diseños de instalación.
Technical Details
Hooks 6
hook_libraries_library_type_info_alter
Permite a los módulos alterar la información de plugins de tipos de biblioteca, como cambiar la clase usada para un tipo de biblioteca específico.
hook_libraries_locator_info_alter
Permite a los módulos alterar la información de plugins localizadores de bibliotecas, habilitando implementaciones de localizadores personalizados.
hook_libraries_version_detector_info_alter
Permite a los módulos alterar la información de plugins detectores de versiones para lógica de detección de versiones personalizada.
hook_libraries_info
(OBSOLETO) Devuelve información sobre bibliotecas externas. Usa archivos de definición de bibliotecas en su lugar. Será eliminado antes de una versión estable.
hook_libraries_info_alter
(OBSOLETO) Altera la información de bibliotecas antes de la detección y el almacenamiento en caché. Útil para añadir archivos de integración a las bibliotecas.
hook_libraries_info_file_paths
(OBSOLETO) Especifica rutas adicionales para buscar archivos de información de bibliotecas. Usa para módulos que declaran muchas bibliotecas.
Drush Commands 2
drush libraries-list
Lista todas las bibliotecas registradas con su estado (OK o tipo de error), versión, variantes instaladas y dependencias. Útil para depurar problemas de instalación de bibliotecas.
drush cache-clear libraries
Limpia la caché de bibliotecas, forzando la re-detección del estado de instalación y versiones de bibliotecas en el próximo acceso.
Troubleshooting 5
Verifica que la biblioteca esté colocada en un directorio soportado (libraries/, sites/all/libraries/, o el directorio libraries/ del perfil). Comprueba que el nombre del directorio coincida con el nombre de máquina de la biblioteca. Usa 'drush libraries-list' para verificar el estado de detección. Asegúrate de que los permisos de archivo permitan que PHP lea los archivos de biblioteca.
Verifica la configuración de version_detector en la definición de biblioteca. Para el detector line_pattern, verifica que la ruta del archivo sea correcta relativa a la raíz de la biblioteca, que el patrón regex coincida con el formato de versión en el archivo, y que los límites de líneas/columnas sean suficientes para alcanzar la cadena de versión.
Limpia la caché de bibliotecas usando 'drush cc libraries' o 'drush cache-clear libraries'. Los resultados de detección de bibliotecas se almacenan en caché y no se actualizarán automáticamente cuando cambien los archivos de biblioteca.
Verifica que definition.remote.enable esté en TRUE en la configuración. Verifica que las URLs de registros remotos sean accesibles. Comprueba si hay problemas de red/firewall. El directorio public://library-definitions debe ser escribible para almacenar las definiciones obtenidas.
Asegúrate de que la biblioteca esté listada en 'library_dependencies' de tu módulo/tema en el archivo info.yml, o que otra extensión habilitada la declare. Libraries API solo registra bibliotecas que son requeridas por extensiones habilitadas. Limpia todas las cachés después de añadir dependencias.
Security Notes 3
- Libraries API carga y ejecuta archivos PHP desde directorios de bibliotecas configurados. Asegúrate de que estos directorios no sean escribibles por usuarios no confiables.
- La obtención remota de definiciones de bibliotecas usa HTTP por defecto (no HTTPS) para la URL del registro predeterminado. Considera usar URLs de registro HTTPS en producción.
- Los archivos de biblioteca se cargan desde rutas del sistema de archivos local. Asegura la configuración apropiada del servidor para prevenir ataques de traversal de directorios o enlaces simbólicos.