README

"下载"插件允许您下载额外的文件（*.zip 或 *.tar.gz）并在您的包内提取它们。

示例

假设您发布了一个依赖外部工件 examplelib-0.1.zip 的PHP包 foo/bar。将此配置放置在 foo/bar 的 composer.json 文件中

{
  "name": "foo/bar",
  "require": {
    "civicrm/composer-downloads-plugin": "~3 || ~4"
  },
  "extra": {
    "downloads": {
      "examplelib": {
        "url": "https://example.com/examplelib-0.1.zip",
        "path": "extern/examplelib",
        "ignore": ["test", "doc", ".*"]
      }
    }
  }
}

当 foo/bar 的下游用户运行 composer install 时，它将获取并提取zip文件，创建 vendor/foo/bar/extern/examplelib。

版本历史

v1.x: lastcall/composer-extra-files 的原始发布
v2.x: 分支。添加测试套件。重命名为 composer-downloads-plugin（extra.downloads）。改进跟踪/重新下载行为。添加更多下载选项。扩展文档。
v3.x: 添加对 composer v2 的支持。
v4.x: 改进PHP 8.2+。交换 gitignore 解析器。删除 composer v1。

评估

composer-downloads-plugin 的主要优点是

简单：它下载一个URL（ZIP/TAR文件）并提取它。它只需要知道两件事：要下载什么（url）和放置在哪里（path）。它作为纯PHP运行，没有外部依赖。
快速：逻辑不需要扫描、索引或映射任何大型注册表。下载系统使用 composer 内置的缓存。
隔离：作为包 foo/bar 的作者，您定义 vendor/foo/bar 目录下的内容。当其他人使用 foo/bar 时，无需特殊说明，无需根级配置，无需与其他包交互。

"下载"插件仅是一个下载机制。请使用它来融合外部资源作为 composer 包的一部分。

"下载"插件不是一个依赖项管理系统。它没有逻辑来扫描注册表、解决传递依赖项、识别版本冲突等。如果需要该功能，则可能需要将 composer 与外部依赖项管理工具集成的桥梁。以下是一些值得考虑的桥梁

配置：属性

extra.downloads 部分包含要下载的文件列表。每个额外文件都有一个符号ID（例如上面的 examplelib）和一些属性组合

url：从该URL获取内容。
path：内容将被提取到的相对路径。
type：(可选) 确定如何处理下载
- archive：url引用一个zip或tarball，应该在给定的 path 中提取。（对于涉及 *.zip、*.tar.gz 或 *.tgz 的URL的默认值。）
- file：url应该下载到给定的 path。（对于所有其他URL的默认值。）
- phar：url引用一个PHP可执行文件，应该在给定的 path 中安装。
ignore：(可选) 一份应从提取文件夹中省略的文件列表。（这支持 .gitignore 表示法的一个子集。）
version（可选）：下载实体的版本号。这不会对实体的生命周期产生功能性的影响，但它可能会影响控制台输出，并且可以可选地用作设置url或path时的变量。

url和path支持以下变量：

{$id}：下载的符号标识符。（在介绍性示例中，它将是examplelib。）
{$version}：包显示/模拟/美观的版本号。

配置：默认值

您可以设置所有下载的默认属性。将它们放在*下，如下所示：

{
  "extra": {
    "downloads": {
      "*": {
        "path": "bower_components/{$id}",
        "ignore": ["test", "tests", "doc", "docs"]
      },
      "jquery": {
        "url": "https://github.com/jquery/jquery-dist/archive/1.12.4.zip"
      },
      "jquery-ui": {
        "url": "https://github.com/components/jqueryui/archive/1.12.1.zip"
      }
    }
  }
}

此示例将：

创建bower_components/jquery（基于jQuery 1.12.4），不包括任何测试/文档文件夹。
创建bower_components/jquery-ui（基于jQueryUI 1.12.1），不包括任何测试/文档文件夹。

提示

在每次下载的文件夹中，此插件将创建一个小型元数据文件夹（.composer-downloads）以跟踪当前代码的来源。如果您修改composer.json以使用不同的URL，那么它将重新下载文件。
将每个额外文件下载到不同的path。不要尝试下载到重叠的路径。（这尚未经过测试，但我预计下载没有很好地排序，您可能会发现更新需要重新下载。）
如果您通常将额外文件下载为*.tar.gz，但有时（对于本地开发）需要从其他地方获取最新的内容，您应该怎么做？只需删除自动下载的文件夹并替换为您自己的。 composer-downloads-plugin将检测到这种冲突（由于缺少.composer-downloads），并将您的代码保持原样（直到您选择将其删除）。要切换回，您可以简单地删除代码并再次运行composer install。

已知限制

如果您在根项目（或符号链接的dev仓库）中使用downloads，它将创建+更新下载，但不会自动删除孤立的项。这可以通过对.composer-downloads进行文件扫描（并删除任何孤立的文件夹）来解决这个问题。由于这种情况目前并不常见，并且文件扫描可能会耗时，因此它可能是一个单独子命令的好主意。

我相信这个限制不会影响依赖项的下层消费者。在这种情况下，常规的composer安装/更新/删除机制应该会处理任何嵌套的下载。

自动化测试

tests/文件夹包含使用PHPUnit编写的单元测试和集成测试。每个集成测试都会生成一个包含合理、代表性的composer.json文件的新文件夹/项目，并执行composer install。它检查输出是否有预期的文件。

要运行测试，您需要在PATH中安装composer和phpunit。

[~/src/composer-downloads-plugin] which composer
/Users/myuser/bin/composer

[~/src/composer-downloads-plugin] which phpunit
/Users/myuser/bin/phpunit

[~/src/composer-downloads-plugin] phpunit
PHPUnit 5.7.27 by Sebastian Bergmann and contributors.

.....                                                               5 / 5 (100%)

Time: 40.35 seconds, Memory: 10.00MB

OK (5 tests, 7 assertions)

集成测试可能有点大/慢。为了更密切地监控测试，设置DEBUG变量，如下所示：

[~/src/composer-downloads-plugin] env DEBUG=2 phpunit

本地开发工具

如果您想创建一个使用当前插件代码的环境——一个可以在迭代代码时快速重新运行composer命令的环境，该怎么办？

您可以使用任何集成测试来初始化基线环境。

env USE_TEST_PROJECT=$HOME/src/myprj DEBUG=2 phpunit tests/SniffTest.php

civicrm / composer-downloads-plugin

维护者

详情