function LibraryDiscoveryParser::parseLibraryInfo

Same name in other branches
  1. 9 core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php \Drupal\Core\Asset\LibraryDiscoveryParser::parseLibraryInfo()
  2. 8.9.x core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php \Drupal\Core\Asset\LibraryDiscoveryParser::parseLibraryInfo()
  3. 11.x core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php \Drupal\Core\Asset\LibraryDiscoveryParser::parseLibraryInfo()

Parses a given library file and allows modules and themes to alter it.

This method sets the parsed information onto the library property.

Library information is parsed from *.libraries.yml files; see editor.libraries.yml for an example. Every library must have at least one js or css entry. Each entry starts with a machine name and defines the following elements:

  • js: A list of JavaScript files to include. Each file is keyed by the file path. An item can have several attributes (like HTML attributes). For example:

  js:
    path/js/file.js: { attributes: { defer: true } }
  

If the file has no special attributes, just use an empty object:


  js:
    path/js/file.js: {}
  

The path of the file is relative to the module or theme directory, unless it starts with a /, in which case it is relative to the Drupal root. If the file path starts with //, it will be treated as a protocol-free, external resource (e.g., //cdn.com/library.js). Full URLs (e.g., http://cdn.com/library.js) as well as URLs that use a valid stream wrapper (e.g., public://path/to/file.js) are also supported.

  • css: A list of categories for which the library provides CSS files. The available categories are:

    • base
    • layout
    • component
    • state
    • theme

    Each category is itself a key for a sub-list of CSS files to include:


  css:
    component:
      css/file.css: {}
  

Just like with JavaScript files, each CSS file is the key of an object that can define specific attributes. The format of the file path is the same as for the JavaScript files. If the JavaScript or CSS file starts with /libraries/ the library.libraries_directory_file_finder service is used to find the files in the following locations:

  • A libraries directory in the current site directory, for example: sites/default/libraries.
  • The root libraries directory.
  • A libraries directory in the selected installation profile, for example: profiles/my_install_profile/libraries.
  • dependencies: A list of libraries this library depends on.
  • version: The library version. The string "VERSION" can be used to mean the current Drupal core version.
  • header: By default, JavaScript files are included in the footer. If the script must be included in the header (along with all its dependencies), set this to true. Defaults to false.
  • minified: If the file is already minified, set this to true to avoid minifying it again. Defaults to false.
  • remote: If the library is a third-party script, this provides the repository URL for reference.
  • license: If the remote property is set, the license information is required. It has 3 properties:

    • name: A System Package Data Exchange (SPDX) license identifier such as "GPL-2.0-or-later" (see https://spdx.org/licenses/), or if not applicable, the human-readable name of the license.
    • url: The URL of the license file/information for the version of the library used.
    • gpl-compatible: A Boolean for whether this library is GPL compatible.

See https://www.drupal.org/node/2274843#define-library for more information.

Parameters

string $extension: The name of the extension that registered a library.

string $path: The relative path to the extension.

Return value

array An array of parsed library data.

Throws

\Drupal\Core\Asset\Exception\InvalidLibraryFileException Thrown when a parser exception got thrown.

1 call to LibraryDiscoveryParser::parseLibraryInfo()
LibraryDiscoveryParser::buildByExtension in core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php
Parses and builds up all the libraries information of an extension.

File

core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php, line 386

Class

LibraryDiscoveryParser
Parses library files to get extension data.

Namespace

Drupal\Core\Asset

Code

protected function parseLibraryInfo($extension, $path) {
    $libraries = [];
    $library_file = $path . '/' . $extension . '.libraries.yml';
    $library_path = $this->root . '/' . $library_file;
    if (file_exists($library_path)) {
        $libraries = $this->fileCache
            ->get($library_path);
        if ($libraries === NULL) {
            try {
                $libraries = Yaml::decode(file_get_contents($this->root . '/' . $library_file)) ?? [];
                $this->fileCache
                    ->set($library_path, $libraries);
            } catch (InvalidDataTypeException $e) {
                // Rethrow a more helpful exception to provide context.
                throw new InvalidLibraryFileException(sprintf('Invalid library definition in %s: %s', $library_file, $e->getMessage()), 0, $e);
            }
        }
    }
    // Core also provides additional libraries that don't come from the YAML,
    // file nor the hook_library_info_build. They come from single-directory
    // component definitions.
    $additional_libraries = $extension === 'core' ? $this->librariesForComponents() : [];
    $libraries = array_merge($additional_libraries, $libraries);
    // Allow modules to add dynamic library definitions.
    $hook = 'library_info_build';
    if ($this->moduleHandler
        ->hasImplementations($hook, $extension)) {
        $libraries = NestedArray::mergeDeep($libraries, $this->moduleHandler
            ->invoke($extension, $hook));
    }
    // Allow modules to alter the module's registered libraries.
    $this->moduleHandler
        ->alter('library_info', $libraries, $extension);
    $this->themeManager
        ->alter('library_info', $libraries, $extension);
    return $libraries;
}

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.