README

此项目模板提供了一套用于使用 Composer 管理网站依赖的入门套件。

重要

Drupal 11 分支可用！

模板做什么？

Drupal 将安装在 web 目录中。
使用由 vendor/autoload.php 生成的 composer 自动加载器，而不是 Drupal 核心提供的 web/vendor/autoload.php。
模块（类型为 drupal-module 的包）将放置在 web/modules/contrib 目录中。
主题（类型为 drupal-theme 的包）将放置在 web/themes/contrib 目录中。
配置文件（类型为 drupal-profile 的包）将放置在 web/profiles/contrib 目录中。
创建默认可写版本的 settings.php 和 services.yml。
创建 web/sites/default/files 目录。
安装 Drush 以作为 vendor/bin/drush 使用。
提供 .env 文件的示例。

安装

注意

以下说明引用了全局 Composer 安装。您可能需要根据您的设置将 composer 替换为 php composer.phar（或类似）。

创建您的项目

composer create-project drupal-composer/drupal-project:10.x-dev some-dir --no-interaction

composer create-project 命令将所有文件的所有权传递给创建的项目。您应该创建一个新的 Git 仓库，并提交所有未被 .gitignore 文件排除的文件。

用法

添加新依赖

使用 composer require 来包含和下载您项目的依赖。

cd some-dir
composer require drupal/devel

默认情况下，此项目设置为仅安装依赖的稳定版本，如 composer.json 中指定的 "minimum-stability": "stable"。如果您需要使用非稳定版本（例如，alpha、beta、RC），您可以修改版本约束以允许此类版本。例如，要要求模块的 beta 版本

composer require drupal/devel:1.0.0-beta1

或者，您可以通过修改 composer.json 来全局调整稳定性设置，包括所需的稳定性级别并显式允许它

{
    "minimum-stability": "beta",
    "prefer-stable": true
}

此配置确保首选稳定版本，但在必要时允许安装非稳定包。

添加库

您可以通过 asset-packagist 存储库使用 Composer 来管理前端资产库。Composer 将检测并安装满足指定约束的新库版本。

composer require bower-asset/dropzone

库的定制安装路径

可以通过将其添加到 extra.installer-paths 配置（在 web/libraries/{$name} 之前）来控制特定库的安装路径。例如，chosen Drupal 模块期望 chosen 库位于 web/libraries/chosen，但 composer require npm-asset/chosen-js 将库安装到 web/libraries/chosen-js。以下配置覆盖安装到预期目录

{
    "extra": {
        "installer-paths": {
            "web/libraries/chosen": [
                "npm-asset/chosen-js"
            ],
            "web/libraries/{$name}": [
                "type:drupal-library",
                "type:npm-asset",
                "type:bower-asset"
            ]
        }
    }
}

有关更多信息，请参阅 https://asset-packagist.org/site/about

更新Drupal核心

此项目将尝试保持所有Drupal核心文件的最新状态；项目使用drupal/core-composer-scaffold确保每次更新drupal/core时，模板文件都得到更新。

如果您自定义了任何“模板”文件（通常是.htaccess），则在Drupal核心的新版本中更新了您修改的文件时，您可能需要合并冲突。

按照以下步骤更新您的Drupal核心文件。

运行composer update "drupal/core-*" --with-dependencies以更新Drupal核心及其依赖项。
运行git diff以确定是否有任何模板文件已更改。检查文件中的任何更改，并将对.htaccess或robots.txt的任何自定义修改恢复。
一次性提交所有内容，以便在检出分支或运行git bisect时，web与core保持同步。
如果在第2步中出现非平凡的冲突，您可能希望在这些步骤上创建一个分支，并使用git merge将更新的核心文件与您的自定义文件合并。这有助于使用kdiff3等三路合并工具。如果您的更改简单，则不需要此设置；将所有修改保持文件开头或结尾是一个很好的策略，以保持合并简单。

常见问题解答（FAQs）

我应该提交我下载的贡献模块吗？

Composer建议不这样做。他们提供了反对的论据，但也提供了如果项目决定这样做的工作区。

我应该提交模板文件吗？

Drupal Composer Scaffold插件可以将模板文件（如index.php、update.php等）下载到项目的web目录。如果您没有自定义这些文件，可以选择不将这些文件提交到您的版本控制系统（例如git）。如果是这种情况，在每次安装或更新项目后自动运行drupal-scaffold插件可能很方便。您可以通过在composer.json中将@composer drupal:scaffold注册为post-install和post-update命令来实现这一点。

"scripts": {
    "post-install-cmd": [
        "@composer drupal:scaffold",
        "..."
    ],
    "post-update-cmd": [
        "@composer drupal:scaffold",
        "..."
    ]
},

如何应用补丁到包含的依赖项？

如果您需要应用补丁，可以使用本项目包含的composer-patches插件。

要将补丁添加到Drupal模块foobar，在composer.json的extra部分插入patches部分。

"extra": {
    "patches": {
        "drupal/foobar": {
            "Patch description": "URL or local path to patch"
        }
    }
}

如何指定PHP版本？

Composer在解析依赖项时会查找以下两个位置的PHP版本要求

composer.json中的require.php版本值。
composer.json中的config.platform版本值。

require.php的目的是为包设置最小PHP语言要求。例如，Drupal 10.0所需的最小版本是8.0.2或更高，可以指定为>=8。

config.platform的目的是为当前环境中运行的包的特定实例设置PHP语言要求。例如，虽然Drupal 10所需的最小版本是8.0.2或更高，但托管提供商的实际PHP版本可能是8.1.0。此字段的值应提供您的确切PHP版本，包含版本的三个部分。

我在Drupal站点中应指定哪些版本？

本项目包含drupal/core，其中已添加了require.php。您将继承此约束。您无需在composer.json中添加require.php。

config.platform是特定平台的。建议指定config.platform为特定版本约束（例如8.1.19），以确保仅使用当前环境支持的包版本。

"config": {
    "platform": {
        "php": "8.1.19"
    }
},

drupal-composer / drupal-project

维护者

详细信息