5 * Documents API functions for Libraries module.
9 * @defgroup libraries External libraries
11 * External libraries are not shipped as part of contributed modules for
12 * licensing and maintenance reasons. The Libraries API module aims to solve the
13 * problem of integrating with and loading external libraries as part of the
14 * Drupal request-response process in a generic way.
16 * @section sec_definitions Library definitions
17 * In order to be useful to other modules Libraries API needs a list of known
18 * libraries and metadata about each of the libraries. Because multiple modules
19 * themes may integrate with the same external library a key objective of
20 * Libraries API is to keep this information separate from any one module or
23 * Definitions are accessed via a discovery that is responsible for checking
24 * whether a given definition exists and fetching it, if it is. See
25 * LibraryRegistryInterface and StreamDefinitionDiscovery for more information.
27 * @subsection sub_definitions_machine_name
28 * A central part of a library's metadata is the library's machine name or ID.
29 * For maximum interoperability it must consist of only lowercase ASCII letters,
30 * numbers, and underscores. As the machine name is the single identifier of a
31 * library and is independent of any given module or theme name it must be
32 * unique among all libraries known to Libraries API.
34 * @subsection sub_definitions_history Historical background
35 * In Drupal 7 library information could already be provided by
36 * module-independent info files, but this was not widely used, because there
37 * was no way to distribute these info files properly. The information was
38 * predominantly provided by a hook that modules could implement, which caused
39 * race conditions between modules providing information for the same library.
40 * Thus, in Drupal 8 there is no longer a hook making it necessary to properly
41 * solve the problem of centrally maintaining and distributing library info
42 * files. This has yet to be done. See https://www.drupal.org/node/773508 for
45 * @section sec_types Library types
46 * Libraries are classed objects that implement LibraryInterface. This generic
47 * interface only dictates that a library is aware of its ID. Any further
48 * functionality depends on the type of library, each type of library comes with
49 * a dedicated interface. See LibraryInterface for more information.
51 * @subsection sub_types_version Version detection
52 * A central aspect of Libraries API is version detection. Modules or themes may
53 * only work with a specific version of an external library, so Libraries API
54 * needs a way to detect the version of a library by inspecting the library
57 * As the mechanism for doing this is generally not specific to any one
58 * library, it is handled by version detector plugins. A 'line_pattern' plugin
59 * that scans a file line by line whether for whether a pattern containing the
60 * version is matched. It can be used if the version is always specified in a
61 * particular place in a particular file, for example a changelog. See
62 * VersionDetectorInterface and LinePatternDetector for more information.
64 * @subsection sub_types_dependency Dependency handling
65 * Many libraries depend on other libraries to function. Thus, most library
66 * classes should implement DependentLibraryInterface to allow libraries to
67 * declare their dependencies as part of their metadata. In case of API changes
68 * in the dependencies libraries need to be able to declare dependencies on
69 * specific versions or version ranges of other libraries. This has yet to be
72 * Furthermore, Libraries API must also maintain a list of libraries that are
73 * required by the installed installation profile, modules, and themes
74 * (extensions). With this information installation of extensions with library
75 * dependencies can be prevented until the libraries are properly installed.
76 * This is currently not implemented. In the future this will be used to
77 * automatically retrieve library definitions of required libraries, and
78 * possibly to automatically download the libraries themselves.
80 * To declare library dependencies extensions can place a 'library_dependencies'
81 * key in their info file with a list of library machine names as the value.
87 * library_dependencies:
92 * @subsection sub_types_asset Asset libraries
93 * With Drupal 8 relying on Composer for autoloading and dependency resolution
94 * of PHP libraries, asset libraries are the primary use-case for Libraries API.
95 * Because asset libraries cannot be loaded ad-hoc, but must be attached to a
96 * renderable element, Libraries API registers external asset libraries that are
97 * required by the installed extensions with the core asset library system. See
98 * AssetLibraryInterface for more information.
100 * @subsection sub_types_php_file
101 * For feature parity with the Drupal 7 version of this module, a PHP file
102 * library type is provided, that can load a list of PHP files on demand.
103 * Generally, it is encouraged to use Composer instead of this library type and
104 * avoid Libraries API altogether for PHP libraries. See PhpFileLibraryInterface
105 * for more information.
107 * This library type might be removed in a future version of Libraries API.
109 * @see \Drupal\libraries\ExternalLibrary\Definition\DefinitionDiscoveryInterface
110 * @see \Drupal\libraries\ExternalLibrary\Definition\StreamDefinitionDiscovery
111 * @see \Drupal\libraries\ExternalLibrary\LibraryInterface
112 * @see \Drupal\libraries\ExternalLibrary\Version\VersionDetectorInterface
113 * @see \Drupal\libraries\Plugin\libraries\VersionDetector\LinePatternDetector
114 * @see \Drupal\libraries\ExternalLibrary\Version\VersionedLibraryInterface
115 * @see \Drupal\libraries\ExternalLibrary\Dependency\DependentLibraryInterface
116 * @see \Drupal\libraries\ExternalLibrary\Asset\AssetLibraryInterface
117 * @see \Drupal\libraries\ExternalLibrary\PhpFile\PhpFileLibraryInterface
123 * Alter library type information.
125 * @param array $library_types
126 * An array of library types keyed by ID. Each library type is an array with
127 * the following keys:
128 * - id: The ID of the library type.
129 * - class: The class to use for this library type.
130 * - provider: The provider of this library type.
132 function hook_libraries_library_type_info_alter(array &$library_types) {
133 // Use a different class for the asset library type. Note that this class is
134 // distinct from the class actually for asset libraries themselves.
135 $library_types['asset']['class'] = 'Drupal\mymodule\ExternalLibrary\BetterAssetLibraryType';
139 * Alter library locator information.
141 * @param array $locators
142 * An array of library locators keyed by ID. Each locator is an array with the
144 * - id: The ID of the library locator.
145 * - class: The class to use for this library locator.
146 * - provider: The provider of this library locator.
148 function hook_libraries_locator_info_alter(array &$locators) {
149 // Use a different class for the stream locator.
150 $locators['stream']['class'] = 'Drupal\mymodule\ExternalLibrary\BetterStreamLocator';
154 * Alter library version detector information.
156 * @param array $version_detectors
157 * An array of library version detectors keyed by ID. Each detector is an
158 * array with the following keys:
159 * - id: The ID of the library version detector.
160 * - class: The class to use for this library version detector.
161 * - provider: The provider of this library version detector.
163 function hook_libraries_version_detector_info_alter(array &$version_detectors) {
164 // Use a different class for the line pattern locator.
165 $version_detectors['line_pattern']['class'] = 'Drupal\mymodule\ExternalLibrary\BetterLinePatternDetector';
169 * Return information about external libraries.
172 * An associative array whose keys are internal names of libraries and whose
173 * values are describing each library. Each key is the directory name below
174 * the 'libraries' directory, in which the library may be found. Each value is
175 * an associative array containing:
176 * - name: The official, human-readable name of the library.
177 * - vendor url: The URL of the homepage of the library.
178 * - download url: The URL of a web page on which the library can be obtained.
179 * - path: (optional) A relative path from the directory of the library to the
180 * actual library. Only required if the extracted download package contains
181 * the actual library files in a sub-directory.
182 * - library path: (optional) The absolute path to the library directory. This
183 * should not be declared normally, as it is automatically detected, to
184 * allow for multiple possible library locations. A valid use-case is an
185 * external library, in which case the full URL to the library should be
187 * - version: (optional) The version of the library. This should not be
188 * declared normally, as it is automatically detected (see 'version
189 * callback' below) to allow for version changes of libraries without code
190 * changes of implementing modules and to support different versions of a
191 * library simultaneously (though only one version can be installed per
192 * site). A valid use-case is an external library whose version cannot be
193 * determined programmatically.
194 * - version callback: (optional) The name of a function that detects and
195 * returns the full version string of the library. The first argument is
196 * always $library, an array containing all library information as described
197 * here. There are two ways to declare the version callback's additional
198 * arguments, either as a single $options parameter or as multiple
199 * parameters, which correspond to the two ways to specify the argument
200 * values (see 'version arguments'). Defaults to libraries_get_version().
201 * - version arguments: A list of arguments to pass to the version callback.
202 * Version arguments can be declared either as an associative array whose
203 * keys are the argument names or as an indexed array without specifying
204 * keys. If declared as an associative array, the arguments get passed to
205 * the version callback as a single $options parameter whose keys are the
206 * argument names (i.e. $options is identical to the specified array). If
207 * declared as an indexed array, the array values get passed to the version
208 * callback as separate arguments in the order they were declared. The
209 * default version callback libraries_get_version() expects a single,
210 * associative array with named keys:
211 * - file: The filename to parse for the version, relative to the library
212 * path. For example: 'docs/changelog.txt'.
213 * - pattern: A string containing a regular expression (PCRE) to match the
214 * library version. For example: '@version\s+([0-9a-zA-Z\.-]+)@'. Note
215 * that the returned version is not the match of the entire pattern (i.e.
216 * '@version 1.2.3' in the above example) but the match of the first
217 * sub-pattern (i.e. '1.2.3' in the above example).
218 * - lines: (optional) The maximum number of lines to search the pattern in.
220 * - cols: (optional) The maximum number of characters per line to take into
221 * account. Defaults to 200. In case of minified or compressed files, this
222 * prevents reading the entire file into memory.
223 * - files: An associative array of library files to load. Supported keys are:
224 * - js: A list of JavaScript files to load, using the same syntax as Drupal
225 * core's hook_library().
226 * - css: A list of CSS files to load, using the same syntax as Drupal
227 * core's hook_library().
228 * - php: A list of PHP files to load.
229 * - dependencies: An array of libraries this library depends on. Similar to
230 * declaring module dependencies, the dependency declaration may contain
231 * information on the supported version. Examples of supported declarations:
233 * $libraries['dependencies'] = array(
234 * // Load the 'example' library, regardless of the version available:
236 * // Only load the 'example' library, if version 1.2 is available:
238 * // Only load a version later than 1.3-beta2 of the 'example' library:
239 * 'example (>1.3-beta2)'
240 * // Only load a version equal to or later than 1.3-beta3:
241 * 'example (>=1.3-beta3)',
242 * // Only load a version earlier than 1.5:
244 * // Only load a version equal to or earlier than 1.4:
246 * // Combinations of the above are allowed as well:
247 * 'example (>=1.3-beta2, <1.5)',
250 * - variants: (optional) An associative array of available library variants.
251 * For example, the top-level 'files' property may refer to a default
252 * variant that is compressed. If the library also ships with a minified and
253 * uncompressed/source variant, those can be defined here. Each key should
254 * describe the variant type, e.g. 'minified' or 'source'. Each value is an
255 * associative array of top-level properties that are entirely overridden by
256 * the variant, most often just 'files'. Additionally, each variant can
257 * contain following properties:
258 * - variant callback: (optional) The name of a function that detects the
259 * variant and returns TRUE or FALSE, depending on whether the variant is
260 * available or not. The first argument is always $library, an array
261 * containing all library information as described here. The second
262 * argument is always a string containing the variant name. There are two
263 * ways to declare the variant callback's additional arguments, either as a
264 * single $options parameter or as multiple parameters, which correspond
265 * to the two ways to specify the argument values (see 'variant
266 * arguments'). If omitted, the variant is expected to always be
268 * - variant arguments: A list of arguments to pass to the variant callback.
269 * Variant arguments can be declared either as an associative array whose
270 * keys are the argument names or as an indexed array without specifying
271 * keys. If declared as an associative array, the arguments get passed to
272 * the variant callback as a single $options parameter whose keys are the
273 * argument names (i.e. $options is identical to the specified array). If
274 * declared as an indexed array, the array values get passed to the
275 * variant callback as separate arguments in the order they were declared.
276 * Variants can be version-specific (see 'versions').
277 * - versions: (optional) An associative array of supported library versions.
278 * Naturally, libraries evolve over time and so do their APIs. In case a
279 * library changes between versions, different 'files' may need to be
280 * loaded, different 'variants' may become available, or Drupal modules need
281 * to load different integration files adapted to the new version. Each key
282 * is a version *string* (PHP does not support floats as keys). Each value
283 * is an associative array of top-level properties that are entirely
284 * overridden by the version.
285 * - integration files: (optional) An associative array whose keys are module
286 * names and whose values are sets of files to load for the module, using
287 * the same notion as the top-level 'files' property. Each specified file
288 * should contain the path to the file relative to the module it belongs to.
289 * - callbacks: An associative array whose keys are callback groups and whose
290 * values are arrays of callbacks to apply to the library in that group.
291 * Each callback receives the following arguments:
292 * - $library: An array of library information belonging to the top-level
293 * library, a specific version, a specific variant or a specific variant
294 * of a specific version. Because library information such as the 'files'
295 * property (see above) can be declared in all these different locations
296 * of the library array, but a callback may have to act on all these
297 * different parts of the library, it is called recursively for each
298 * library with a certain part of the libraries array passed as $library
300 * - $version: If the $library array belongs to a certain version (see
301 * above), a string containing the version. This argument may be empty, so
302 * NULL should be specified as the default value.
303 * - $variant: If the $library array belongs to a certain variant (see
304 * above), a string containing the variant name. This argument may be
305 * empty, so NULL should be specified as the default value.
306 * Valid callback groups are:
307 * - info: Callbacks registered in this group are applied after the library
308 * information has been retrieved via hook_libraries_info() or info files.
309 * - pre-detect: Callbacks registered in this group are applied after the
310 * library path has been determined and before the version callback is
311 * invoked. At this point the following additional information is available:
312 * - $library['library path']: The path on the file system to the library.
313 * - post-detect: Callbacks registered in this group are applied after the
314 * library has been successfully detected. At this point the library
315 * contains the version-specific information, if specified, and following
316 * additional information is available:
317 * - $library['installed']: A boolean indicating whether the library is
319 * - $library['version']: If it could be detected, a string containing the
320 * version of the library.
321 * - $library['variants'][$variant]['installed']: For each specified
322 * variant, a boolean indicating whether the variant is installed or
324 * Note that in this group the 'versions' property is no longer available.
325 * - pre-load: Callbacks registered in this group are applied directly
326 * before this library is loaded. At this point the library contains
327 * variant-specific information, if specified. Note that in this group the
328 * 'variants' property is no longer available.
329 * - post-load: Callbacks registered in this group are applied directly
330 * after this library is loaded. At this point, the library contains a
331 * 'loaded' key, which contains the number of files that were loaded.
332 * Additional top-level properties can be registered as needed.
334 * @see hook_library()
336 * @deprecated Will be removed before a stable Drupal 8 release.
338 function hook_libraries_info() {
339 // The following is a full explanation of all properties. See below for more
340 // concrete example implementations.
342 // This array key lets Libraries API search for 'sites/all/libraries/example'
343 // directory, which should contain the entire, original extracted library.
344 $libraries['example'] = array(
345 // Only used in administrative UI of Libraries API.
346 'name' => 'Example library',
347 'vendor url' => 'http://example.com',
348 'download url' => 'http://example.com/download',
349 // Optional: If, after extraction, the actual library files are contained in
350 // 'sites/all/libraries/example/lib', specify the relative path here.
352 // Optional: Define a custom version detection callback, if required.
353 'version callback' => 'mymodule_get_version',
354 // Specify arguments for the version callback. By default,
355 // libraries_get_version() takes a named argument array:
356 'version arguments' => array(
357 'file' => 'docs/CHANGELOG.txt',
358 'pattern' => '@version\s+([0-9a-zA-Z\.-]+)@',
362 // Default list of files of the library to load. Important: Only specify
363 // third-party files belonging to the library here, not integration files of
366 // 'js' and 'css' follow the syntax of hook_library(), but file paths are
367 // relative to the library path.
376 // For PHP libraries, specify include files here, still relative to the
383 // Optional: Specify alternative variants of the library, if available.
385 // All properties defined for 'minified' override top-level properties.
390 'gadgets/foo.min.js',
397 'variant callback' => 'mymodule_check_variant',
398 'variant arguments' => array(
399 'variant' => 'minified',
403 // Optional, but usually required: Override top-level properties for later
404 // versions of the library. The properties of the minimum version that is
405 // matched override the top-level properties. Note:
406 // - When registering 'versions', it usually does not make sense to register
407 // 'files', 'variants', and 'integration files' on the top-level, as most
408 // of those likely need to be different per version and there are no
410 // - The array keys have to be strings, as PHP does not support floats for
415 'js' => array('exlib.js'),
416 'css' => array('exlib_style.css'),
421 'js' => array('exlib.js'),
422 'css' => array('lib_style.css'),
438 // Optional: Register files to auto-load for your module. All files must be
439 // keyed by module, and follow the syntax of the 'files' property.
440 'integration files' => array(
442 'js' => array('ex_lib.inc'),
445 // Optionally register callbacks to apply to the library during different
446 // stages of its lifetime ('callback groups').
447 'callbacks' => array(
448 // Used to alter the info associated with the library.
450 'mymodule_example_libraries_info_callback',
452 // Called before detecting the given library.
453 'pre-detect' => array(
454 'mymodule_example_libraries_predetect_callback',
456 // Called after detecting the library.
457 'post-detect' => array(
458 'mymodule_example_libraries_postdetect_callback',
460 // Called before the library is loaded.
462 'mymodule_example_libraries_preload_callback',
464 // Called after the library is loaded.
465 'post-load' => array(
466 'mymodule_example_libraries_postload_callback',
471 // A very simple library. No changing APIs (hence, no versions), no variants.
472 // Expected to be extracted into 'sites/all/libraries/simple'.
473 $libraries['simple'] = array(
474 'name' => 'Simple library',
475 'vendor url' => 'http://example.com/simple',
476 'download url' => 'http://example.com/simple',
477 'version arguments' => array(
478 'file' => 'readme.txt',
479 // Best practice: Document the actual version strings for later reference.
481 'pattern' => '/Version (\d+)/',
485 'js' => array('simple.js'),
489 // A library that (naturally) evolves over time with API changes.
490 $libraries['tinymce'] = array(
492 'vendor url' => 'http://tinymce.moxiecode.com',
493 'download url' => 'http://tinymce.moxiecode.com/download.php',
494 'path' => 'jscripts/tiny_mce',
495 // The regular expression catches two parts (the major and the minor
496 // version), which libraries_get_version() doesn't allow.
497 'version callback' => 'tinymce_get_version',
498 'version arguments' => array(
499 // It can be easier to parse the first characters of a minified file
500 // instead of doing a multi-line pattern matching in a source file. See
501 // 'lines' and 'cols' below.
502 'file' => 'jscripts/tiny_mce/tiny_mce.js',
503 // Best practice: Document the actual version strings for later reference.
504 // 2.x: this.majorVersion="2";this.minorVersion="1.3"
505 // 3.x: majorVersion:'3',minorVersion:'2.0.1'
506 'pattern' => '@majorVersion[=:]["\'](\d).+?minorVersion[=:]["\']([\d\.]+)@',
513 'js' => array('tiny_mce.js'),
518 'js' => array('tiny_mce_src.js'),
522 'integration files' => array(
524 'js' => array('editors/js/tinymce-2.js'),
525 'css' => array('editors/js/tinymce-2.css'),
529 // Definition used if 3.1 or above is detected.
531 // Does not support JS aggregation.
534 'tiny_mce.js' => array('preprocess' => FALSE),
538 // New variant leveraging jQuery. Not stable yet; therefore not the
543 'tiny_mce_jquery.js' => array('preprocess' => FALSE),
550 'tiny_mce_src.js' => array('preprocess' => FALSE),
555 'integration files' => array(
557 'js' => array('editors/js/tinymce-3.js'),
558 'css' => array('editors/js/tinymce-3.css'),
568 * Alter the library information before detection and caching takes place.
570 * The library definitions are passed by reference. A common use-case is adding
571 * a module's integration files to the library array, so that the files are
572 * loaded whenever the library is. As noted above, it is important to declare
573 * integration files inside of an array, whose key is the module name.
575 * @see hook_libraries_info()
577 * @deprecated Will be removed before a stable Drupal 8 release.
579 function hook_libraries_info_alter(&$libraries) {
581 'php' => array('example_module.php_spellchecker.inc'),
583 $libraries['php_spellchecker']['integration files']['example_module'] = $files;
587 * Specify paths to look for library info files.
589 * Libraries API looks in the following directories for library info files by
592 * - profiles/$profile/libraries
593 * - sites/all/libraries
594 * - sites/$site/libraries
595 * This hook allows you to specify additional locations to look for library info
596 * files. This should only be used for modules that declare many libraries.
597 * Modules that only implement a few libraries should implement
598 * hook_libraries_info().
603 * @deprecated Will be removed before a stable Drupal 8 release.
605 function hook_libraries_info_file_paths() {
606 // Taken from the Libraries test module, which needs to specify the path to
608 return array(drupal_get_path('module', 'libraries_test') . '/example');