README

此项目提供了一个Composer插件，用于将drupal/core项目中的脚手架文件（如index.php、update.php等）放置到Web根目录中的指定位置。只能使用此插件脚手架单个文件。

脚手架文件的目的在于允许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之后发生，涉及将所需的资产复制或创建符号链接到目标位置。为了防止任意依赖关系通过脚手架机制复制文件，只有被顶级项目特别允许的项目才会用于脚手架文件。

示例：允许从项目 drupal/core 脚手架

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

允许包脚手架文件还允许它将脚手架权限委派给它本身所依赖的任何项目。这允许包根据其需要组织其脚手架资产。例如，项目drupal/core可以选择将其资产存储在子项目drupal/assets中。

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

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

允许顶级项目构建的项目将依次使用，allowed-packages 列表中声明较晚的项目将具有比之前命名的项目更高的优先级。顶级 composer.json 本身始终隐式允许构建文件，并且其构建文件具有最高优先级。

定义项目位置

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

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

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

如果没有显式定义 web 根，则默认为 ./。

修改构建文件

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

以下示例显示了一个项目，它将额外的条目追加到由 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"
    ]
  }

定义构建文件

构建资源的放置由提供它们的控制项目控制，但位置始终相对于由根项目定义的目录（通常是 web 根）。例如，以下片段显示了构建文件 robots.txt 从其源位置 assets/robots.txt 复制到 web 根。

{
  "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": [
  "drupal/core",
],

file-mapping

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

以下列出了可用的属性：

模式：可以是 "replace"、"append" 或 "skip" 之一。
path：要覆盖目标文件而写入源文件的路径。
prepend：要追加到目标文件中的源文件路径，这必须始终是来自其他项目的支架文件。
append：与 prepend 类似，但追加内容而不是预置。
overwrite：如果 false，则防止在目标已存在时发生 replace。

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

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": "^1.2",
    "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": {
      "allowed-packages": [
        "drupal/core"
      ],
      "locations": {
        "web-root": "./docroot"
      },
      "symlink": true,
      "overwrite": 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",
        "[web-root]/web.config": "assets/web.config"
      }
    }
  }
}

实现 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"
]

greg-1-anderson / drupal-core-composer-scaffold

维护者

详细信息