Libraries API
Drupalモジュール向けの外部ライブラリ管理機能を提供し、サードパーティ製JavaScript、CSS、PHPライブラリのバージョン依存管理と共有利用を可能にします。
libraries
インストール
composer require 'drupal/libraries:^4.1'
composer require 'drupal/libraries:^4.0'
概要
Libraries APIは、Drupalで外部（サードパーティ）ライブラリを管理するための統一された柔軟なフレームワークを提供します。モジュールやテーマが外部ライブラリへの依存関係を宣言でき、それらの検出、バージョンチェック、読み込みを自動的に処理します。
このモジュールは、Drupalコアのアセットシステムと統合するアセットライブラリ（JavaScriptおよびCSSファイル）、レガシーコード用のPHPファイルライブラリ、複数のコンポーネントを含むマルチアセットライブラリなど、様々なライブラリタイプをサポートしています。ライブラリはURIベースのロケーターやグローバル設定など、様々な方法で配置場所を特定できます。
ライブラリ定義はローカルに保存するか、Drupal Libraries Registryなどのリモートレジストリから取得できます。このモジュールはライブラリファイル内のパターンマッチングによるバージョン検出機能を提供し、互換性要件が満たされていることを確認します。有効なモジュールやテーマがinfoファイルでライブラリ依存関係を宣言すると、Libraries APIは必要な外部ライブラリをDrupalコアのライブラリシステムに自動的に登録します。
Features
- 拡張性のためのプラグインベースアーキテクチャを採用した外部ライブラリ管理システム
- Drupalコアのライブラリアタッチメントシステムと統合するアセットライブラリ（JavaScript/CSS）のサポート
- オンデマンドで読み込み可能なPHPファイルライブラリのサポート
- 複数のコンポーネントを含むライブラリ向けのマルチアセットライブラリサポート
- 設定可能な検出器（行パターンマッチング、静的バージョン）によるバージョン検出
- 様々なファイルシステムの場所でライブラリを検索するロケータープラグイン
- 複数の場所を順番に試すチェーンロケーター
- settingsによるグローバルロケーター設定
- ストリームラッパー（asset://、php-file://）を使用したURIベースのロケーター
- Drupal Libraries Registryなどのレジストリからのリモートライブラリ定義取得
- 自動キャッシュ機能付きのローカルライブラリ定義ストレージ
- 後方互換性のためのレガシーAPIサポート（hook_libraries_info、libraries_load、libraries_get_path）
- 'library_dependencies'キーを使用したモジュール/テーマのinfoファイルでのライブラリ依存関係宣言
- 登録済みライブラリの一覧表示とライブラリキャッシュクリアのためのDrush統合
- ライブラリファイルにアクセスするためのストリームラッパー（asset://、php-file://、library-definitions://）
Use Cases
モジュールでのライブラリ依存関係の宣言
モジュールの.info.ymlファイルに必要な外部ライブラリのマシン名をリストした'library_dependencies'キーを追加します。Libraries APIがこれらのライブラリを自動的に検出して登録します。例：library_dependencies: ['flexslider', 'jquery_mobile']。ライブラリは$element['#attached']['library'][] = 'libraries/flexslider'でアタッチできるようになります。
ライブラリ定義ファイルの作成
public://library-definitions/にライブラリのマシン名（例：'mylib.json'）でJSONファイルを作成します。タイプ（'asset'、'php_file'、または'asset_multiple'）、version_detector設定、ファイル宣言を含めます。アセットライブラリの場合、Drupalコアのライブラリ構造に従って'css'と'js'配列を指定します。例：{"type": "asset", "version_detector": {"id": "static", "configuration": {"version": "1.0"}}, "js": {"mylib.js": {}}, "css": {"base": {"mylib.css": {}}}}
ライブラリマネージャーサービスの使用
'libraries.manager'サービスをインジェクトまたは取得して、プログラム的にライブラリ情報にアクセスします。getLibrary($id)を使用して検出ステータスとメタデータを持つライブラリオブジェクトを取得します。PHPファイルライブラリにはload($id)を使用してファイルを明示的に読み込みます。getRequiredLibraryIds()を使用して有効な拡張機能が必要とする全てのライブラリを取得します。
カスタムバージョン検出の実装
非標準のバージョン形式を持つライブラリには、カスタム正規表現パターン、対象ファイルパス、行数/列数制限を設定した'line_pattern'バージョン検出器を設定します。ライブラリ定義内：{"version_detector": {"id": "line_pattern", "configuration": {"file": "CHANGELOG.md", "pattern": "/@version\\s+([0-9.]+)/", "lines": 50}}}
グローバルライブラリ配置場所の設定
libraries.settings設定にglobal_locatorsを追加して、ライブラリを検索するカスタム場所を指定します。各ロケーターはIDと設定を持つプラグインです。カスタムURIロケーターの例：global_locators: [{id: 'uri', configuration: {uri: 'public://custom-libraries'}}]
レガシーLibraries APIの使用
後方互換性のため、モジュールはlibraries_load($name)でライブラリを読み込み、libraries_get_path($name)でライブラリのファイルシステムパスを取得し、hook_libraries_info()でライブラリ情報を宣言できます。これらは非推奨ですが、移行目的で引き続き機能します。
Tips
- バージョンをプログラム的に検出できないライブラリにはstatic version検出器を使用しますが、インストールされているバージョンが確実な場合にのみ使用してください。
- asset://ストリームラッパーはデフォルトでsites/all/assets/vendorを指します - 自動検出のためにアセットライブラリをそこに配置してください。
- php-file://ストリームラッパーはデフォルトでsites/all/librariesを指します - PHPライブラリをそこに配置してください。
- ライブラリ定義はサイトのservices.ymlでlibraries.definition.discoveryサービスをオーバーライドすることで、JSONの代わりにYAML形式を使用できます。
- 開発時には、ローカル定義のみを使用するためにリモート定義取得を無効（definition.remote.enable: false）にしてください。
- PHP依存関係にComposerを使用する場合、Libraries APIのphp_fileライブラリタイプよりもComposerのオートローディングを優先してください。
- ライブラリの複数のバリアント（例：圧縮版とソース版）はレガシーのhook_libraries_info()実装で宣言できます。
- chainロケーターは優先順位で複数の場所を試すことができます - 様々なインストールレイアウトをサポートするのに便利です。
Technical Details
Hooks 6
hook_libraries_library_type_info_alter
モジュールがライブラリタイププラグイン情報を変更できるようにします。特定のライブラリタイプに使用されるクラスの変更などが可能です。
hook_libraries_locator_info_alter
モジュールがライブラリロケータープラグイン情報を変更できるようにし、カスタムロケーター実装を可能にします。
hook_libraries_version_detector_info_alter
モジュールがバージョン検出器プラグイン情報を変更できるようにし、カスタムバージョン検出ロジックを可能にします。
hook_libraries_info
（非推奨）外部ライブラリに関する情報を返します。代わりにライブラリ定義ファイルを使用してください。安定版リリース前に削除される予定です。
hook_libraries_info_alter
（非推奨）検出とキャッシュの前にライブラリ情報を変更します。ライブラリに統合ファイルを追加するのに便利です。
hook_libraries_info_file_paths
（非推奨）ライブラリinfoファイルを検索する追加パスを指定します。多くのライブラリを宣言するモジュールに使用します。
Drush Commands 2
drush libraries-list
登録済みの全ライブラリをステータス（OKまたはエラータイプ）、バージョン、インストール済みバリアント、依存関係とともに一覧表示します。ライブラリインストールの問題をデバッグするのに便利です。
drush cache-clear libraries
ライブラリキャッシュをクリアし、次回アクセス時にライブラリのインストールステータスとバージョンを強制的に再検出します。
Troubleshooting 5
ライブラリがサポートされているディレクトリ（libraries/、sites/all/libraries/、またはプロファイルのlibraries/ディレクトリ）に配置されていることを確認してください。ディレクトリ名がライブラリのマシン名と一致していることを確認してください。'drush libraries-list'を使用して検出ステータスを確認してください。PHPがライブラリファイルを読み取れるように適切なファイル権限を確認してください。
ライブラリ定義のversion_detector設定を確認してください。line_pattern検出器の場合、ファイルパスがライブラリルートからの相対パスとして正しいこと、正規表現パターンがファイル内のバージョン形式と一致すること、行数/列数制限がバージョン文字列に到達するのに十分であることを確認してください。
'drush cc libraries'または'drush cache-clear libraries'を使用してライブラリキャッシュをクリアしてください。ライブラリ検出結果はキャッシュされ、ライブラリファイルが変更されても自動的に更新されません。
設定でdefinition.remote.enableがTRUEであることを確認してください。リモートレジストリURLにアクセスできることを確認してください。ネットワーク/ファイアウォールの問題を確認してください。取得した定義を保存するためにpublic://library-definitionsディレクトリが書き込み可能である必要があります。
ライブラリがモジュール/テーマのinfo.ymlファイルの'library_dependencies'にリストされているか、または他の有効な拡張機能がそれを宣言していることを確認してください。Libraries APIは有効な拡張機能が必要とするライブラリのみを登録します。依存関係を追加した後は全てのキャッシュをクリアしてください。
Security Notes 3
- Libraries APIは設定されたライブラリディレクトリからPHPファイルを読み込んで実行します。これらのディレクトリが信頼できないユーザーによって書き込み可能でないことを確認してください。
- リモートライブラリ定義取得はデフォルトレジストリURLではHTTP（HTTPSではなく）を使用します。本番環境ではHTTPSレジストリURLの使用を検討してください。
- ライブラリファイルはローカルファイルシステムパスから読み込まれます。ディレクトリトラバーサルやシンボリックリンク攻撃を防ぐための適切なサーバー設定を確認してください。