README

Composer Upstream Files 插件由 Last Call Media 的朋友带来，这个 Composer 插件允许您从各种上游源更新属于您应用程序的文件。这个插件有几个不同的使用场景：

• 您有某些应用程序依赖项的特定版本所需的文件，但这些文件需要作为您应用程序的一部分存在。例如，当您使用基于 Composer 的安装时，Drupal 的 index.php 文件是必需的，但必须位于 core 目录之外。
• 您有希望允许修改的文件（因此它们不适合包含在库中），但希望在不同项目之间保持同步。例如，默认的 .eslintrc 或 phpcs.xml.dist。

在所有情况下，由此插件管理的文件应提交到应用程序的仓库。 此插件不会自动更新这些文件 - 它只提供您可以使用以更新它们的 Composer 命令 - 您应定期执行此操作，然后审查并提交结果更改。

安装

使用 Composer 在您的应用程序中安装此插件

composer require --dev lastcall/composer-upstream-files

用法

上游文件定义在您的 composer.json 的 extra 部分。示例

{
  "name": "my-awesome-site",
  "require": {
    "my/package": "^1.0.0"
  },
  "extra": {
    "upstream-files": {
      "files": {
        "https://raw.githubusercontent.com/LastCallMedia/Drupal-Scaffold/circle20/.editorconfig": ".editorconfig",
        "https://raw.githubusercontent.com/LastCallMedia/Drupal-Scaffold/circle20/web/.htaccess": "web/.htaccess"
      }
    }
  }
}

在此示例中，我们定义了两个具有上游源文件的文件。files 数组的键是源，值是目标。当我们运行 composer upstream-files:update 时，这两个文件将从它们各自的 URL 中刷新。然后我们会审查并提交更改。

令牌

此插件支持使用令牌来减少您需要输入和更新的内容量。令牌用双括号括起来。示例

{
  "extra": {
    "upstream-files": {
      "tokens": {
        "scaffold": "https://raw.githubusercontent.com/LastCallMedia/Drupal-Scaffold",
        "drupal": "https://raw.githubusercontent.com/drupal/drupal/{{drupal/core.version}}"
      },
      "files": {
        "{{drupal}}/index.php": "web/index.php",
        "{{scaffold}}/.editorconfig": ".editorconfig"
      }
    }
  }
}

您可以在 tokens 键下定义任何您希望使用的令牌，并将它们用作 files 的替换。此外，您可以通过使用 {{PACKAGENAME.version}}（如我们在上面 drupal/core 所做的那样）来引用已安装包的当前版本。令牌会被递归替换，所以如果你的令牌包含另一个令牌，那是可以的。

清单

您还可以引用“清单”，即包含上游文件规范的 JSON 文件。这些清单可以是本地的或远程的。请看这个例子

// composer.json
{
  "extra": {
    "upstream-files": {
      "tokens": {
        "scaffoldBranch": "master"
      },
      "manifests": [
        "drupal.json",
        "http://github.com/LastCallMedia/Drupal-Scaffold/upstream-files.json"
      ]
    }
  }
}

// drupal.json
{
  "tokens": {
    "drupal": "https://raw.githubusercontent.com/drupal/drupal/{{drupal/core.version}}"
  },
  "files": {
    "{{drupal}}/index.php": "web/index.php",
  }
}

// http://github.com/LastCallMedia/Drupal-Scaffold/upstream-files.json
{
  "tokens": {
    "scaffold": "https://raw.githubusercontent.com/LastCallMedia/Drupal-Scaffold/{{scaffoldBranch}}"
  },
  "files": {
    "{{scaffold}}/.editorconfig": ".editorconfig"
  }
}

清单还可以指定其他清单，这在需要指定大量文件时很有用。

排除

还可以根据源或目标排除文件。这在您使用上游项目的清单时最有用，并且不希望从上游拉取某些文件

{
  "extra": {
    "upstream-files": {
      "manifests": [
        "drupal.json",
      ],
      "sourceExcludes": [
        "@LastCallMedia/Drupal-Scaffold@"
      ],
      "destinationExcludes": [
        "/\\.gitattributes/"
      ]
    }
  }
}

sourceExcludes 和 destinationExcludes 属性都是正则表达式的数组，表示您希望排除的文件。 sourceExcludes 将与完全解析的源 URL 匹配，而 destinationExcludes 将与完全解析的目标路径匹配。