README

该项目提供了一个Composer插件，使Drupal核心Composer包能在Composer项目中正确工作。

这包括以下内容

将骨架文件（如index.php，update.php等）从drupal/core项目放置到网站根目录下的期望位置。使用此插件只能对单个文件进行骨架构建。
将包含Composer autoload.php文件的autoload.php文件写入网站根目录。

骨架文件的目的在于允许Drupal站点完全由Composer管理，同时允许将单个资产文件放置在任意位置。这样做是为了使正确配置的composer模板能够生成与Drupal 8.7.x及以前tarball分发版文件布局完全匹配的文件布局。其他文件布局也将是可能的；例如，一个与当前drupal-composer/drupal-project模板非常相似的项目布局也将被提供。当使用这些项目之一时，用户应该能够在提取下载的归档文件后立即使用composer require和composer update命令在Drupal站点上操作。

注意，Drupal站点的依赖项只有在顶级composer.json文件中明确授予该权限的情况下才能构建文件。有关详细信息，请参阅下文的允许的包。

使用方法

Drupal Composer Scaffold通过在项目的composer.json文件的extra部分提供配置设置，并在项目中要求drupal/core-composer-scaffold来实现。还会参考项目依赖项的composer.json文件中的额外配置来构建项目需要的文件。还可以在骨架文件的开头或结尾添加更多信息，就像通常对.htaccess和robots.txt文件所做的那样。有关更多信息，请参阅修改骨架文件。

通常，骨架操作在需要时自动运行，例如在composer install之后，因此一旦在项目composer.json文件中设置了配置，通常不需要做任何不同的事情来构建项目。要直接构建文件，请运行

composer drupal:scaffold

允许的包

骨架文件存储在主项目composer.json文件中要求的项目中，就像通常那样。骨架操作发生在composer install之后，涉及将所需的资产复制或符号链接到目标位置。为了防止任意依赖通过骨架机制复制文件，只有那些顶级项目明确允许的项目才会用于构建文件。

示例：允许从项目upstream/project中进行骨架构建

  "name": "my/project",
  ...
  "extra": {
    "drupal-scaffold": {
      "allowed-packages": [
        "upstream/project"
      ],
      ...
    }
  }

允许一个包构建文件也允许它将构建权限委派给它自己要求的任何项目。这允许包根据其需要组织其骨架资产。例如，如果upstream/project将其资产存储在子项目upstream/assets中，则隐式允许upstream/assets构建文件。

项目可以从多个项目中获取骨架文件。例如，一个使用分发版的Drupal项目，在特定的网络托管服务提供商上安装时，可能从以下来源获取其骨架文件：

Drupal核心
其分布
由托管提供商提供的项目
项目本身

允许顶级项目搭建的每个项目将依次使用，allowed-packages 列表中声明较晚的项目将优先于之前命名的项目。隐式允许 drupal/core 并将其放在列表顶部。顶级 composer.json 本身也隐式允许搭建文件，其搭建文件具有最高优先级。

定义项目位置

顶级项目必须定义网站根目录的位置。它通过以下所示的 locations 映射来实现

  "name": "my/project",
  ...
  "extra": {
    "drupal-scaffold": {
      "locations": {
        "web-root": "./docroot"
      },
      ...
    }
  }

这使得可以为项目配置不同的文件布局；例如，可以使用 drupal/drupal 文件布局或 drupal-composer/drupal-project 文件布局来设置项目。

如果没有显式定义网站根目录，则默认为 .，与 composer.json 文件相同的目录。

修改搭建文件

有时，一个项目可能希望使用依赖项提供的搭建文件，但对其进行某种修改。支持两种修改形式：追加和修补。

以下示例显示了一个项目，它将额外的条目追加到 drupal/core 提供的 robots.txt 文件末尾

  "name": "my/project",
  ...
  "extra": {
    "drupal-scaffold": {
      "file-mapping": {
        "[web-root]/robots.txt": {
          "append": "assets/my-robots-additions.txt",
        }
      }
    }
  }

也可以通过包含一个提供要追加到搭建文件的相对路径的 "prepend" 条目来在追加之前或之后追加到搭建文件。

以下示例演示了使用 post-drupal-scaffold-cmd 钩子通过修补来修改 .htaccess 文件

  "name": "my/project",
  ...
  "scripts": {
    "post-drupal-scaffold-cmd": [
      "cd docroot && patch -p1 <../patches/htaccess-ssl.patch"
    ]
  }

定义搭建文件

搭建资产的放置由提供它们的项控制，但位置始终相对于根项目定义的某个目录——通常是网站根目录。例如，以下代码片段中的搭建文件 robots.txt 从其源位置 assets/robots.txt 复制到网站根目录。

{
  "name": "drupal/assets",
  ...
  "extra": {
    "drupal-scaffold": {
      "file-mapping": {
        "[web-root]/robots.txt": "assets/robots.txt",
        ...
      }
    }
  }
}

排除搭建文件

有时，一个项目可能更喜欢完全替换由依赖项提供的搭建文件，并且不接收进一步的更新。可以通过将搭建文件的排除值设置为 false 来完成此操作

  "name": "my/project",
  ...
  "extra": {
    "drupal-scaffold": {
      "file-mapping": {
        "[web-root]/robots.txt": false
      }
    }
  }

如果可能，请使用如上所述的修改搭建文件中解释的 append 和 prepend 指令。排除文件意味着您的项目将不会获得任何针对已修改的文件的错误修复或其他更新。

覆盖

默认情况下，搭建文件将覆盖目标位置上的任何内容。有时，项目可能希望为将不会在后续更新中更改的文件提供初始内容。这可以通过将 overwrite 标志设置为 false 来完成，如下面的示例所示

{
  "name": "service-provider/d8-scaffold-files",
  "extra": {
    "drupal-scaffold": {
      "file-mapping": {
        "[web-root]/sites/default/settings.php": {
          "mode": "replace",
          "path": "assets/sites/default/settings.php",
          "overwrite": false
        }
      }
    }
  }
}

请注意，overwrite 指令旨在由启动工具、服务提供商等使用。单个 Drupal 网站应通过将其值设置为 false 来排除文件。

自动加载文件

搭建工具在搭建操作过程中自动在 Drupal 根目录创建所需的 autoload.php 文件。此文件不应以任何方式进行修改或自定义。如果已将其提交到仓库，则搭建工具将停止管理它。如果由于任何原因更改了 vendor 目录的位置，并且 autoload.php 文件已提交到仓库，则手动删除它，然后运行 composer install 以更新它。

规范

以下列出了“composer.json”文件中“extra”部分“drupal-scaffold”部分的配置指令的参考部分。

allowed-packages

allowed-packages配置设置包含一个有序列表的包名，这些包名将在构建阶段使用。

"allowed-packages": [
  "example/assets",
],

file-mapping

file-mapping配置设置由一个从构建文件的目标路径到控制如何构建文件的属性集的映射组成。

可用的属性如下

mode: “replace”、“append”或“skip”中的一个。
path: 要覆盖目标文件的源文件的路径。
prepend: 要添加到目标文件中的源文件的路径，这必须始终是其他项目提供的构建文件。
append: 与prepend类似，但追加内容而不是添加。
overwrite: 如果设置为false，则如果目标已存在，则阻止发生替换。

模式可能可以从其他属性推断。如果未指定模式，则将提供以下默认值

replace: 如果存在path属性，或者条目的值是字符串而不是属性集，则选择。
append: 如果存在prepend或append属性，则选择。
skip: 如果条目的值是布尔值false，则选择。

示例

"file-mapping": {
  "[web-root]/sites/default/default.settings.php": {
    "mode": "replace",
    "path": "assets/sites/default/default.settings.php",
    "overwrite": true
  },
  "[web-root]/sites/default/settings.php": {
    "mode": "replace",
    "path": "assets/sites/default/settings.php",
    "overwrite": false
  },
  "[web-root]/robots.txt": {
    "mode": "append",
    "prepend": "assets/robots-prequel.txt",
    "append": "assets/robots-append.txt"
  },
  "[web-root]/.htaccess": {
    "mode": "skip",
  }
}

上述示例的简短形式如下

"file-mapping": {
  "[web-root]/sites/default/default.settings.php": "assets/sites/default/default.settings.php",
  "[web-root]/sites/default/settings.php": {
    "path": "assets/sites/default/settings.php",
    "overwrite": false
  },
  "[web-root]/robots.txt": {
    "prepend": "assets/robots-prequel.txt",
    "append": "assets/robots-append.txt"
  },
  "[web-root]/.htaccess": false
}

请注意，没有明确的“prepend”模式；“append”模式用于同时追加和添加到构建文件。这样做的原因是，构建文件条目在文件映射部分根据其目标路径进行标识，并且不可能有多个条目具有相同的键。如果“prepend”是一个单独的模式，那么将无法同时追加和添加到同一个文件。

默认情况下，追加操作只能应用于由之前评估的项目构建的文件。但是，如果向append操作添加了force-append属性，则只有在追加文本尚未出现在文件中时，才会将追加应用到非构建文件中。使用此模式时，还可以提供在目标文件完全缺失时使用的默认内容。

以下示例演示了构建settings-custom.php文件，并将其包含在现有的settings.php文件中。

"file-mapping": {
  "[web-root]/sites/default/settings-custom.php": "assets/settings-custom.php",
  "[web-root]/sites/default/settings.php": {
    "append": "assets/include-settings-custom.txt",
    "force-append": true,
    "default": "assets/initial-default-settings.txt"
  }
}

请注意，如果与构建settings.php文件的项目一起使用，上述示例仍然有效。

gitignore

gitignore配置设置控制此插件是否将管理构建操作期间写入的.gitignore文件。

true: 当构建文件写入时，将更新.gitignore文件。
false: 永远不会修改.gitignore文件。
未设置：如果目标目录是git存储库的本地工作副本，并且在该存储库中忽略vendor目录，则将更新.gitignore文件。

locations

locations配置设置包含一个命名位置的列表，这些位置可用于放置构建文件。必需的位置是web-root。如果需要，也可以定义其他位置。

"locations": {
  "web-root": "./docroot"
},

symlink

symlink属性导致replace操作创建到源文件的符号链接而不是复制它。这对于进行核心开发很有用，因为符号链接文件本身不应被编辑。请注意，append操作覆盖了symlink选项，以防止修改原始构建资产。

"symlink": true,

管理构建文件

应将构建文件的处理方式与处理vendor目录的方式相同。如果您需要提交vendor（例如，以便部署您的站点），则还应提交您的构建文件。除非有必要，否则不应提交vendor目录或构建文件。

如果依赖项提供的脚手架文件中将overwrite设置为false，则该文件应提交到您的仓库。

默认情况下，当编写脚手架文件时，如果需要，将自动更新.gitignore文件。请参阅上方规格部分中的gitignore设置。

示例

下面有一些完整的示例。

依赖composer-scaffold的项目示例composer.json

{
  "name": "my/project",
  "require": {
    "drupal/core-composer-scaffold": "*",
    "composer/installers": "^2.3",
    "cweagans/composer-patches": "^1.6.5",
    "drupal/core": "^8.8.x-dev",
    "service-provider/d8-scaffold-files": "^1"
  },
  "config": {
    "optimize-autoloader": true,
    "sort-packages": true
  },
  "extra": {
    "drupal-scaffold": {
      "locations": {
        "web-root": "./docroot"
      },
      "symlink": true,
      "file-mapping": {
        "[web-root]/.htaccess": false,
        "[web-root]/robots.txt": "assets/robots-default.txt"
      }
    }
  }
}

将资产放置在不同项目的drupal/core示例composer.json

{
  "name": "drupal/core",
  "extra": {
    "drupal-scaffold": {
      "allowed-packages": [
        "drupal/assets",
      ]
    }
  }
}

drupal/assets中composer-scaffold文件的示例composer.json

{
  "name": "drupal/assets",
  "extra": {
    "drupal-scaffold": {
      "file-mapping": {
        "[web-root]/.csslintrc": "assets/.csslintrc",
        "[web-root]/.editorconfig": "assets/.editorconfig",
        "[web-root]/.eslintignore": "assets/.eslintignore",
        "[web-root]/.eslintrc.json": "assets/.eslintrc.json",
        "[web-root]/.gitattributes": "assets/.gitattributes",
        "[web-root]/.ht.router.php": "assets/.ht.router.php",
        "[web-root]/.htaccess": "assets/.htaccess",
        "[web-root]/sites/default/default.services.yml": "assets/default.services.yml",
        "[web-root]/sites/default/default.settings.php": "assets/default.settings.php",
        "[web-root]/sites/example.settings.local.php": "assets/example.settings.local.php",
        "[web-root]/sites/example.sites.php": "assets/example.sites.php",
        "[web-root]/index.php": "assets/index.php",
        "[web-root]/robots.txt": "assets/robots.txt",
        "[web-root]/update.php": "assets/update.php",
      }
    }
  }
}

实现composer-scaffold的库示例composer.json

{
  "name": "service-provider/d8-scaffold-files",
  "extra": {
    "drupal-scaffold": {
      "file-mapping": {
        "[web-root]/sites/default/settings.php": "assets/sites/default/settings.php"
      }
    }
  }
}

追加到robots.txt

{
  "name": "service-provider/d8-scaffold-files",
  "extra": {
    "drupal-scaffold": {
      "file-mapping": {
        "[web-root]/robots.txt": {
          "append": "assets/my-robots-additions.txt",
        }
      }
    }
  }
}

复制文件后修补它

"post-drupal-scaffold-cmd": [
  "cd docroot && patch -p1 <../patches/htaccess-ssl.patch"
]

drupal / core-composer-scaffold

维护者

详细信息