README

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

这是 lastcall/composer-extra-files 的更新版本。它添加了集成测试，修复了一些错误，并做了一些其他改进。一些配置选项已更改，因此已重命名以防止在实际使用中发生冲突。

示例

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

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

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

假设您的存档下载 URL 不包含文件扩展名。请将 type 和 ext 添加到包部分。

{
  "name": "foo/bar",
  "require": {
    "civicrm/composer-downloads-plugin": "~2.1"
  },
  "extra": {
    "downloads": {
      "examplelib": {
        "url": "https://example.com/examplelib-0.1?type=zip",
        "type": "archive",
        "ext": "zip",  
        "path": "extern/examplelib",
        "ignore": ["test", "doc", ".*"]
      }
    }
  }
}

评估

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 或 tar 文件，应在指定的 path 下提取。（默认用于涉及 *.zip、*.tar.gz 或 *.tgz 的 URL。）
- file：url 应下载到指定的 path。（默认用于所有其他 URL。）
- phar：url 引用的是 PHP 可执行文件，应在指定的 path 下安装。
ext：(可选) 指定 type: archive 的文件扩展名
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。

已知限制

如果您在根项目（或符号链接的开发仓库）中使用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

evotodi / composer-downloads-plugin

维护者

详细信息