README

Drupal Libraries Installer 是一个 composer 插件，允许轻松管理 Drupal 模块/主题所需的外部库，这些库不是作为 composer 包提供的。此插件是实现管理 Drupal 网站所有外部依赖项的解决方案的一部分：在单个位置——composer.json 文件中。

如何使用

将 Drupal Libraries Installer 添加到您的 Drupal 网站项目
```
composer require zodiacmedia/drupal-libraries-installer
```

通过在 extra 中的 drupal-libraries 属性中添加库，将库添加到您的 composer.json 文件中。使用库的名称作为键，以及其分发 ZIP/RAR/TAR/TGZ/TAR.GZ/TAR.BZ2 文件 URL 作为值来指定库。它将尝试从 URL 中猜测库类型。如果文件不是 ZIP 文件，则 URL 必须以文件扩展名结尾

{
    "extra": {
        "drupal-libraries": {
            "chosen": "https://github.com/harvesthq/chosen/releases/download/v1.8.2/chosen_v1.8.2.zip",
            "flexslider": "https://github.com/woocommerce/FlexSlider/archive/2.6.4.zip",
            "moment": "https://registry.npmjs.org/moment/-/moment-2.25.0.tgz"
        }
    }
}

或者如果您想指定更详细定义

{
    "extra": {
        "drupal-libraries": {
            "chosen": {
                "url": "https://github.com/harvesthq/chosen/releases/download/v1.8.2/chosen_v1.8.2.zip"
            },
            "flexslider": {
                "url": "https://github.com/woocommerce/FlexSlider/archive/2.6.4.zip",
                "version": "2.6.4",
                "type": "zip",
                "ignore": ["bower_components", "demo", "node_modules"]
            },
            "moment": {
                "url": "https://registry.npmjs.org/moment/-/moment-2.25.0.tgz",
                "shasum": "e961ab9a5848a1cf2c52b1af4e6c82a8401e7fe9"
            },
            "select2": {
                 "url": "https://github.com/select2/select2/archive/4.0.13.zip",
                 "ignore": [
                     ".*",
                     "*.{md}",
                     "Gruntfile.js",
                     "{docs,src,tests}"
                 ],
                 "rename": {
                     "dist": "build"                  
                 }                   
            },
            "custom-tar-asset": {
                 "url": "https://assets.custom-url.com/unconventional/url/path",
                 "type": "tar",
                 "ignore": [".*", "*.{txt,md}"]
            }
        }
    }
}

配置选项如下

url：库 URL（必填）。
version：库版本（默认为 1.0.0）。
type：库存档类型，以下之一（zip, tar, rar, gzip），支持取决于您的 composer 版本（默认为 zip）。
ignore：要从中删除库的文件夹/文件 glob 数组（默认为 []）。有关更多信息，请参阅 PSA-2011-002。
rename：文件夹/文件到重命名对象映射，以适应特定文件夹结构（可选）。
shasum：资产的 SHA1 哈希（可选）。

以下是如何找到 GitHub 存储库的 ZIP URL。

确保 composer 包类型为 drupal-library 已配置为安装到正确的路径。默认情况下，composer/installers（此插件的依赖项，并且可能已包含在您的项目中）将安装这些包到您的 repo 根目录的 /libraries/{$name}/ 中。您可能希望通过在 composer.json 的 installer-paths 属性（在 extra 中）中更改它来修改此行为。
```
{
    "extra": {
        "installer-paths": {
            "web/libraries/{$name}/": ["type:drupal-library"]
        }
    }
}
```
有关 installer-paths 属性的更多信息，请参阅 composer/installers 的 README。
运行 composer install。运行 composer install 或 composer update 时将下载并解压缩库。要升级库，只需在您的 composer.json 文件中更换其 URL，然后再次运行 composer install 即可。

安装由其他包声明的库。

将 drupal-libraries-dependencies extra 属性设置为 true 以获取项目中所有包声明的库。始终使用库的第一个声明，因此如果您发现多个包需要同一库的不同版本，您可以在项目的 composer.json 中声明正确的版本。

{
    "extra": {
        "drupal-libraries-dependencies": true
    }
}

或者，您可以通过将其设置为要拉入库的包数组来限制它（推荐）。

{
    "extra": {
        "drupal-libraries-dependencies": [
          "drupal/project1",
          "drupal/project2"
        ]
    }
}

如何引用 npm 包。

例如，如果您想下载 moment npm 包的版本 2.25.0。

运行 npm view moment@2.25.0。
使用 .tarball 值作为库的 url。
使用 .shasum 值作为库的 shasum。

如何将 GitHub 仓库引用为 ZIP 文件

如果您被指示从其 GitHub 仓库下载库，请按照以下说明查找代码库的 ZIP 文件版本的链接

首选方法

最好引用库的特定版本，以便每个项目的用户每次都下载相同的代码版本。要查看可用的版本

单击 GitHub 仓库首页顶部附近的 X 版本 链接（其中 X 是某个数字）。您也可以通过在仓库的首页 URL 后追加 /releases/ 来到达版本页面，例如，对于 https://github.com/harvesthq/chosen，您将转到 https://github.com/harvesthq/chosen/releases/。
确定您想使用的版本。除非模块注明了特定的版本要求，否则您可能希望使用最新版本。
对于该版本，找到“资产”部分。如果仓库提供了自己的分发 ZIP 文件，那么它将作为列表中的第一个文件列出之一。如果是这样，您可能希望首先尝试使用它，以防它包含在仓库中直接不可用的预构建文件。否则，使用该版本的“源代码（zip）”链接。只需复制所需链接的 URL 以在您的 composer.json 文件中使用。

备选方法

如果库没有提供任何版本，您仍然可以将其以 ZIP 文件的形式引用。缺点是每次您下载此 ZIP 文件时，其内容可能根据仓库的状态而更改。无法保证项目不同的用户将具有库的确切相同版本。为了减轻此问题，您应始终下载特定提交版本的库，而不是从如 master 这样的分支。

单击仓库首页上的绿色 克隆或下载 按钮。
将 下载 ZIP 链接的 URL 复制到您的 composer.json 文件中。

具有命名空间的库定义

如果库包含供应商命名空间，则其内部包名称将以前缀 drupal-library_ 开头，例如 vendor/library 变为 drupal-library_vendor/library，这允许您添加如下自定义安装选项来管理其下载位置

{
  // composer.json
  "extra": {
    "installer-paths": {
      // Custom installer path entry to store them all under the same folder.
      "web/libraries/myvendor/{$name}": [
        "vendor:drupal-library_ckeditor"
      ],
      "web/libraries/{$name}/": [
        "type:drupal-library"
      ]
    },
    "drupal-libraries": {
      "myvendor/package1": "https://download.myvendor.com/package1-1.0.0.zip",
      "myvendor/package2": "https://download.myvendor.com/package2-1.4.0.zip"
    }
  },
}

否则，文件将默认存储在 web/libraries/myvendor 中，并将相互覆盖。

注意：installer-paths 的顺序很重要。

前缀的理由是为了避免与正常的 composer 包发生任何潜在的冲突。

备注

此插件基本上是显式声明每个库 zip 文件的项目中需要包含的 composer 包信息的快捷方式，例如

{
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "harvesthq/chosen",
                "version": "1.8.2",
                "type": "drupal-library",
                "dist": {
                  "url": "https://github.com/harvesthq/chosen/releases/download/v1.8.2/chosen_v1.8.2.zip",
                  "type": "zip"
                }
            }
        }
    ],
    "require": {
        "harvesthq/chosen": "1.8.2"
    }
}

虽然此方法完全可行，并且无需任何其他插件即可直接使用，但它也很繁琐，不太用户友好，并且相当冗长，给 composer.json 文件添加了大量的额外噪声。

由于库是在实际 composer 包安装之后安装的，因此它们不受 composer 内在的依赖关系解决算法的影响。这意味着库不能指定兼容版本的范围（而是必须选择库分发文件的特定版本），如果库有自己的其他库依赖项，则必须将这些依赖项明确添加到列表中。
由于库是在 composer 包之后安装的，因此在安装路径冲突的情况下，可能由此插件安装的库会覆盖 composer 包。
虽然许多库基于JS和/或CSS，并通过npm提供，但无法使用npm将这些包直接安装到正确的/libraries/文件夹中。此外，模块通常会列出它们的外部库需求，作为ZIP分发文件或GitHub仓库的链接，使得使用此插件以这种方式引用和拉取这些依赖项更加方便。

zodiacmedia / drupal-libraries-installer

维护者

详细信息