You are here

class LibraryDiscoveryParser in Drupal 10

Same name and namespace in other branches
  1. 8 core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php \Drupal\Core\Asset\LibraryDiscoveryParser
  2. 9 core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php \Drupal\Core\Asset\LibraryDiscoveryParser

Parses library files to get extension data.

Hierarchy

Expanded class hierarchy of LibraryDiscoveryParser

1 file declares its use of LibraryDiscoveryParser
LibraryDiscoveryParserTest.php in core/tests/Drupal/Tests/Core/Asset/LibraryDiscoveryParserTest.php
Contains \Drupal\Tests\Core\Asset\LibraryDiscoveryParserTest.
1 string reference to 'LibraryDiscoveryParser'
core.services.yml in core/core.services.yml
core/core.services.yml
1 service uses LibraryDiscoveryParser
library.discovery.parser in core/core.services.yml
Drupal\Core\Asset\LibraryDiscoveryParser

File

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

Namespace

Drupal\Core\Asset
View source
class LibraryDiscoveryParser {

  /**
   * The module handler.
   *
   * @var \Drupal\Core\Extension\ModuleHandlerInterface
   */
  protected $moduleHandler;

  /**
   * The theme manager.
   *
   * @var \Drupal\Core\Theme\ThemeManagerInterface
   */
  protected $themeManager;

  /**
   * The app root.
   *
   * @var string
   */
  protected $root;

  /**
   * The stream wrapper manager.
   *
   * @var \Drupal\Core\StreamWrapper\StreamWrapperManagerInterface
   */
  protected $streamWrapperManager;

  /**
   * The libraries directory file finder.
   *
   * @var \Drupal\Core\Asset\LibrariesDirectoryFileFinder
   */
  protected $librariesDirectoryFileFinder;

  /**
   * The extension path resolver.
   *
   * @var \Drupal\Core\Extension\ExtensionPathResolver
   */
  protected $extensionPathResolver;

  /**
   * Constructs a new LibraryDiscoveryParser instance.
   *
   * @param string $root
   *   The app root.
   * @param \Drupal\Core\Extension\ModuleHandlerInterface $module_handler
   *   The module handler.
   * @param \Drupal\Core\Theme\ThemeManagerInterface $theme_manager
   *   The theme manager.
   * @param \Drupal\Core\StreamWrapper\StreamWrapperManagerInterface $stream_wrapper_manager
   *   The stream wrapper manager.
   * @param \Drupal\Core\Asset\LibrariesDirectoryFileFinder $libraries_directory_file_finder
   *   The libraries directory file finder.
   * @param \Drupal\Core\Extension\ExtensionPathResolver $extension_path_resolver
   *   The extension path resolver.
   */
  public function __construct($root, ModuleHandlerInterface $module_handler, ThemeManagerInterface $theme_manager, StreamWrapperManagerInterface $stream_wrapper_manager, LibrariesDirectoryFileFinder $libraries_directory_file_finder, ExtensionPathResolver $extension_path_resolver) {
    $this->root = $root;
    $this->moduleHandler = $module_handler;
    $this->themeManager = $theme_manager;
    $this->streamWrapperManager = $stream_wrapper_manager;
    $this->librariesDirectoryFileFinder = $libraries_directory_file_finder;
    $this->extensionPathResolver = $extension_path_resolver;
  }

  /**
   * Parses and builds up all the libraries information of an extension.
   *
   * @param string $extension
   *   The name of the extension that registered a library.
   *
   * @return array
   *   All library definitions of the passed extension.
   *
   * @throws \Drupal\Core\Asset\Exception\IncompleteLibraryDefinitionException
   *   Thrown when a library has no js/css/setting.
   * @throws \UnexpectedValueException
   *   Thrown when a js file defines a positive weight.
   */
  public function buildByExtension($extension) {
    if ($extension === 'core') {
      $path = 'core';
      $extension_type = 'core';
    }
    else {
      if ($this->moduleHandler
        ->moduleExists($extension)) {
        $extension_type = 'module';
      }
      else {
        $extension_type = 'theme';
      }
      $path = $this->extensionPathResolver
        ->getPath($extension_type, $extension);
    }
    $libraries = $this
      ->parseLibraryInfo($extension, $path);
    $libraries = $this
      ->applyLibrariesOverride($libraries, $extension);
    foreach ($libraries as $id => &$library) {
      if (!isset($library['js']) && !isset($library['css']) && !isset($library['drupalSettings']) && !isset($library['dependencies'])) {
        throw new IncompleteLibraryDefinitionException(sprintf("Incomplete library definition for definition '%s' in extension '%s'", $id, $extension));
      }
      $library += [
        'dependencies' => [],
        'js' => [],
        'css' => [],
      ];
      if (isset($library['header']) && !is_bool($library['header'])) {
        throw new \LogicException(sprintf("The 'header' key in the library definition '%s' in extension '%s' is invalid: it must be a boolean.", $id, $extension));
      }
      if (isset($library['version'])) {

        // @todo Retrieve version of a non-core extension.
        if ($library['version'] === 'VERSION') {
          $library['version'] = \Drupal::VERSION;
        }
        elseif (is_string($library['version']) && $library['version'][0] === 'v') {
          $library['version'] = substr($library['version'], 1);
        }
      }

      // If this is a 3rd party library, the license info is required.
      if (isset($library['remote']) && !isset($library['license'])) {
        throw new LibraryDefinitionMissingLicenseException(sprintf("Missing license information in library definition for definition '%s' extension '%s': it has a remote, but no license.", $id, $extension));
      }

      // Assign Drupal's license to libraries that don't have license info.
      if (!isset($library['license'])) {
        $library['license'] = [
          'name' => 'GNU-GPL-2.0-or-later',
          'url' => 'https://www.drupal.org/licensing/faq',
          'gpl-compatible' => TRUE,
        ];
      }
      foreach ([
        'js',
        'css',
      ] as $type) {

        // Prepare (flatten) the SMACSS-categorized definitions.
        // @todo After Asset(ic) changes, retain the definitions as-is and
        //   properly resolve dependencies for all (css) libraries per category,
        //   and only once prior to rendering out an HTML page.
        if ($type == 'css' && !empty($library[$type])) {
          assert(static::validateCssLibrary($library[$type]) < 2, 'CSS files should be specified as key/value pairs, where the values are configuration options. See https://www.drupal.org/node/2274843.');
          assert(static::validateCssLibrary($library[$type]) === 0, 'CSS must be nested under a category. See https://www.drupal.org/node/2274843.');
          foreach ($library[$type] as $category => $files) {
            $category_weight = 'CSS_' . strtoupper($category);
            assert(defined($category_weight), 'Invalid CSS category: ' . $category . '. See https://www.drupal.org/node/2274843.');
            foreach ($files as $source => $options) {
              if (!isset($options['weight'])) {
                $options['weight'] = 0;
              }

              // Apply the corresponding weight defined by CSS_* constants.
              $options['weight'] += constant($category_weight);
              $library[$type][$source] = $options;
            }
            unset($library[$type][$category]);
          }
        }
        foreach ($library[$type] as $source => $options) {
          unset($library[$type][$source]);

          // Allow to omit the options hashmap in YAML declarations.
          if (!is_array($options)) {
            $options = [];
          }
          if ($type == 'js' && isset($options['weight']) && $options['weight'] > 0) {
            throw new \UnexpectedValueException("The {$extension}/{$id} library defines a positive weight for '{$source}'. Only negative weights are allowed (but should be avoided). Instead of a positive weight, specify accurate dependencies for this library.");
          }

          // Unconditionally apply default groups for the defined asset files.
          // The library system is a dependency management system. Each library
          // properly specifies its dependencies instead of relying on a custom
          // processing order.
          if ($type == 'js') {
            $options['group'] = JS_LIBRARY;
          }
          elseif ($type == 'css') {
            $options['group'] = $extension_type == 'theme' ? CSS_AGGREGATE_THEME : CSS_AGGREGATE_DEFAULT;
          }

          // By default, all library assets are files.
          if (!isset($options['type'])) {
            $options['type'] = 'file';
          }
          if ($options['type'] == 'external') {
            $options['data'] = $source;
          }
          else {
            if ($source[0] === '/') {

              // An absolute path maps to DRUPAL_ROOT / base_path().
              if ($source[1] !== '/') {
                $source = substr($source, 1);

                // Non core provided libraries can be in multiple locations.
                if (strpos($source, 'libraries/') === 0) {
                  $path_to_source = $this->librariesDirectoryFileFinder
                    ->find(substr($source, 10));
                  if ($path_to_source) {
                    $source = $path_to_source;
                  }
                }
                $options['data'] = $source;
              }
              else {
                $options['type'] = 'external';
                $options['data'] = $source;
              }
            }
            elseif ($this->streamWrapperManager
              ->isValidUri($source)) {
              $options['data'] = $source;
            }
            elseif ($this
              ->isValidUri($source)) {
              $options['type'] = 'external';
              $options['data'] = $source;
            }
            else {
              $options['data'] = $path . '/' . $source;
            }
          }
          if (!isset($library['version'])) {

            // @todo Get the information from the extension.
            $options['version'] = -1;
          }
          else {
            $options['version'] = $library['version'];
          }

          // Set the 'minified' flag on JS file assets, default to FALSE.
          if ($type == 'js' && $options['type'] == 'file') {
            $options['minified'] = $options['minified'] ?? FALSE;
          }
          $library[$type][] = $options;
        }
      }
    }
    return $libraries;
  }

  /**
   * 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:
   *   @code
   *   js:
   *     path/js/file.js: { attributes: { defer: true } }
   *   @endcode
   *   If the file has no special attributes, just use an empty object:
   *   @code
   *   js:
   *     path/js/file.js: {}
   *   @endcode
   *   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:
   *   @code
   *   css:
   *     component:
   *       css/file.css: {}
   *   @endcode
   *   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: 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.
   *
   * @param string $extension
   *   The name of the extension that registered a library.
   * @param string $path
   *   The relative path to the extension.
   *
   * @return array
   *   An array of parsed library data.
   *
   * @throws \Drupal\Core\Asset\Exception\InvalidLibraryFileException
   *   Thrown when a parser exception got thrown.
   */
  protected function parseLibraryInfo($extension, $path) {
    $libraries = [];
    $library_file = $path . '/' . $extension . '.libraries.yml';
    if (file_exists($this->root . '/' . $library_file)) {
      try {
        $libraries = Yaml::decode(file_get_contents($this->root . '/' . $library_file)) ?? [];
      } 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);
      }
    }

    // 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;
  }

  /**
   * Apply libraries overrides specified for the current active theme.
   *
   * @param array $libraries
   *   The libraries definitions.
   * @param string $extension
   *   The extension in which these libraries are defined.
   *
   * @return array
   *   The modified libraries definitions.
   */
  protected function applyLibrariesOverride($libraries, $extension) {
    $active_theme = $this->themeManager
      ->getActiveTheme();

    // ActiveTheme::getLibrariesOverride() returns libraries-overrides for the
    // current theme as well as all its base themes.
    $all_libraries_overrides = $active_theme
      ->getLibrariesOverride();
    foreach ($all_libraries_overrides as $theme_path => $libraries_overrides) {
      foreach ($libraries as $library_name => $library) {

        // Process libraries overrides.
        if (isset($libraries_overrides["{$extension}/{$library_name}"])) {
          if (isset($library['deprecated'])) {
            $override_message = sprintf('Theme "%s" is overriding a deprecated library.', $extension);
            $library_deprecation = str_replace('%library_id%', "{$extension}/{$library_name}", $library['deprecated']);
            @trigger_error("{$override_message} {$library_deprecation}", E_USER_DEPRECATED);
          }

          // Active theme defines an override for this library.
          $override_definition = $libraries_overrides["{$extension}/{$library_name}"];
          if (is_string($override_definition) || $override_definition === FALSE) {

            // A string or boolean definition implies an override (or removal)
            // for the whole library. Use the override key to specify that this
            // library will be overridden when it is called.
            // @see \Drupal\Core\Asset\LibraryDiscovery::getLibraryByName()
            if ($override_definition) {
              $libraries[$library_name]['override'] = $override_definition;
            }
            else {
              $libraries[$library_name]['override'] = FALSE;
            }
          }
          elseif (is_array($override_definition)) {

            // An array definition implies an override for an asset within this
            // library.
            foreach ($override_definition as $sub_key => $value) {

              // Throw an exception if the asset is not properly specified.
              if (!is_array($value)) {
                throw new InvalidLibrariesOverrideSpecificationException(sprintf('Library asset %s is not correctly specified. It should be in the form "extension/library_name/sub_key/path/to/asset.js".', "{$extension}/{$library_name}/{$sub_key}"));
              }
              if ($sub_key === 'drupalSettings') {

                // drupalSettings may not be overridden.
                throw new InvalidLibrariesOverrideSpecificationException(sprintf('drupalSettings may not be overridden in libraries-override. Trying to override %s. Use hook_library_info_alter() instead.', "{$extension}/{$library_name}/{$sub_key}"));
              }
              elseif ($sub_key === 'css') {

                // SMACSS category should be incorporated into the asset name.
                foreach ($value as $category => $overrides) {
                  $this
                    ->setOverrideValue($libraries[$library_name], [
                    $sub_key,
                    $category,
                  ], $overrides, $theme_path);
                }
              }
              else {
                $this
                  ->setOverrideValue($libraries[$library_name], [
                  $sub_key,
                ], $value, $theme_path);
              }
            }
          }
        }
      }
    }
    return $libraries;
  }

  /**
   * Determines if the supplied string is a valid URI.
   */
  protected function isValidUri($string) {
    return count(explode('://', $string)) === 2;
  }

  /**
   * Overrides the specified library asset.
   *
   * @param array $library
   *   The containing library definition.
   * @param array $sub_key
   *   An array containing the sub-keys specifying the library asset, e.g.
   *   ['js'] or ['css', 'component'].
   * @param array $overrides
   *   Specifies the overrides, this is an array where the key is the asset to
   *   be overridden while the value is overriding asset.
   * @param string $theme_path
   *   The theme or base theme.
   */
  protected function setOverrideValue(array &$library, array $sub_key, array $overrides, $theme_path) {
    foreach ($overrides as $original => $replacement) {

      // Get the attributes of the asset to be overridden. If the key does
      // not exist, then throw an exception.
      $key_exists = NULL;
      $parents = array_merge($sub_key, [
        $original,
      ]);

      // Save the attributes of the library asset to be overridden.
      $attributes = NestedArray::getValue($library, $parents, $key_exists);
      if ($key_exists) {

        // Remove asset to be overridden.
        NestedArray::unsetValue($library, $parents);

        // No need to replace if FALSE is specified, since that is a removal.
        if ($replacement) {

          // Ensure the replacement path is relative to drupal root.
          $replacement = $this
            ->resolveThemeAssetPath($theme_path, $replacement);
          $new_parents = array_merge($sub_key, [
            $replacement,
          ]);

          // Replace with an override if specified.
          NestedArray::setValue($library, $new_parents, $attributes);
        }
      }
    }
  }

  /**
   * Ensures that a full path is returned for an overriding theme asset.
   *
   * @param string $theme_path
   *   The theme or base theme.
   * @param string $overriding_asset
   *   The overriding library asset.
   *
   * @return string
   *   A fully resolved theme asset path relative to the Drupal directory.
   */
  protected function resolveThemeAssetPath($theme_path, $overriding_asset) {
    if ($overriding_asset[0] !== '/' && !$this
      ->isValidUri($overriding_asset)) {

      // The destination is not an absolute path and it's not a URI (e.g.
      // public://generated_js/example.js or http://example.com/js/my_js.js), so
      // it's relative to the theme.
      return '/' . $theme_path . '/' . $overriding_asset;
    }
    return $overriding_asset;
  }

  /**
   * Validates CSS library structure.
   *
   * @param array $library
   *   The library definition array.
   *
   * @return int
   *   Returns based on validity:
   *     - 0 if the library definition is valid
   *     - 1 if the library definition has improper nesting
   *     - 2 if the library definition specifies files as an array
   */
  public static function validateCssLibrary($library) {
    $categories = [];

    // Verify options first and return early if invalid.
    foreach ($library as $category => $files) {
      if (!is_array($files)) {
        return 2;
      }
      $categories[] = $category;
      foreach ($files as $options) {
        if (!is_array($options)) {
          return 1;
        }
      }
    }
    return 0;
  }

}

Members