README

此项目模板应该为使用Composer管理您的站点依赖项提供起点。

这是对drupal-composer/drupal-project的分支，该分支默认支持持续集成。

额外功能

此分支相对于drupal-project原始版本有以下新增功能

• 可定制的构建：使用Phing创建了针对生产环境和开发环境的不同构建。这些可以通过一组配置文件完全自定义。
• Behat支持：包含Behat，以便您可以轻松测试用户场景。
• 预配置的测试套件：PHPUnit已完全配置，可用于运行单元测试、内核测试、Web测试和JavaScript测试。
• PHP CodeSniffer：使用单个命令检查编码标准的合规性，或设置它以在您git push时自动扫描。
• Travis CI：与Travis CI无缝集成，因此您可以从一开始就自动化测试。无需设置！

如果您想了解如何将其用作Drush Make的替代方案，请访问drupal.org上的文档。

用法

首先您需要安装Composer。

注意：下面的说明参考了全局Composer安装。您可能需要根据您的配置将composer替换为php composer.phar（或类似）。

之后您可以创建项目

git clone https://github.com/dennisdigital/drupal-project.git some-dir
cd some-dir
composer install

使用composer require ...，您可以下载新的依赖项到您的安装。

composer require drupal/devel:~1.0

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

composer create-project dennisdigital/drupal-project:8.x-dev /some-dir --stability dev --no-interaction

模板做什么？

在安装给定的composer.json时，会处理一些任务

• 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。
• 创建sites/default/files目录。
• 在本地安装最新版本的drush，以便在vendor/bin/drush中使用。
• 在本地安装最新版本的DrupalConsole，以便在vendor/bin/drupal中使用。

更新Drupal核心

本项目旨在确保您的Drupal核心文件始终保持最新状态；使用项目drupal-composer/drupal-scaffold确保每次更新drupal/core时，您的scaffold文件都会更新。如果您对任何“scaffolding”文件（通常是 .htaccess）进行了自定义，那么在Drupal核心的新版本中更新您修改的文件时，您可能需要解决合并冲突。

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

1. 运行composer update drupal/core --with-dependencies以更新Drupal核心及其依赖项。
2. 运行git diff以确定是否有任何scaffold文件已更改。检查文件中的任何更改，并恢复对.htaccess或robots.txt的任何自定义设置。
3. 将所有内容作为一个单独的提交提交，这样在检出分支或运行git bisect时，web将与core保持同步。
4. 如果在第2步中出现非平凡的冲突，您可能希望在分支上执行以下步骤，并使用git merge将更新的核心文件与您的自定义文件合并。这有助于使用kdiff3之类的三路合并工具。如果您的更改很简单，则不需要此设置；将所有修改放在文件的开始或结束部分是一种很好的策略，以简化合并。

从现有项目生成composer.json

使用"Composer Generate" drush扩展，您现在可以从现有项目生成基本的composer.json文件。请注意，生成的composer.json可能与本项目文件不同。

自定义构建属性

使用您最喜欢的文本编辑器在项目根目录中创建一个名为build.properties.local的新文件

$ vim build.properties.local

该文件将包含适用于您开发机器的唯一配置。这主要用于指定您的数据库凭据和Drupal管理员的用户名和密码，以便在安装期间使用。

因为这些设置是个人设置，所以不应与团队的其他成员共享。请确保您永远不要提交此文件！

您可以在build.properties.dist文件中找到所有可用的选项。只需复制您想要覆盖的行并更改其值。例如

# The location of the Composer binary.
composer.bin = /usr/bin/composer

# Database settings.
drupal.db.name = my_database
drupal.db.user = root
drupal.db.password = hunter2

# Admin user.
drupal.admin.username = admin
drupal.admin.password = admin

# The base URL to use in tests.
drupal.base_url = http://platform.local

# Verbosity of Drush commands. Set to 'yes' for verbose output.
drush.verbose = yes

列出可用的构建命令

您可以使用以下命令获取所有可用的Phing构建命令（“目标”）及其每个目标的简短描述

$ ./vendor/bin/phing

安装网站。

$ ./vendor/bin/phing install

设置开发环境工具

如果您想安装适合开发的版本，可以执行setup-dev Phing目标。

$ ./vendor/bin/phing setup-dev

这将执行以下任务

1. 配置Behat。
2. 配置PHP CodeSniffer。
3. 启用“开发模式”。这将

• 启用development.services.yml中的服务。
• 显示所有错误消息和回溯信息。
• 禁用CSS和JS聚合。
• 禁用渲染缓存。
• 允许安装测试模块和主题。
• 启用对rebuild.php的访问。

1. 启用开发模块。
2. 为每个用户角色创建一个演示用户。

为了快速设置开发环境，您可以通过执行install和setup-dev目标同时执行install-dev。

$ ./vendor/bin/phing install-dev

运行Behat测试

Behat测试套件位于tests/文件夹中。运行它们的最简单方法是进入该文件夹并执行以下命令

$ cd tests/
$ ./behat

如果您想执行单个测试，只需提供测试的路径作为参数。测试位于tests/features/。

$ cd tests/
$ ./behat features/authentication.feature

如果您想执行一组测试中的一个测试，请使用标签。使用~排除标签。

$ cd tests/
$ ./behat --tags="@api&&@user"

如果您想从不同的文件夹运行测试，请使用-c选项提供tests/behat.yml的路径。

# Run the tests from the root folder of the project.
$ ./vendor/bin/behat -c tests/behat.yml

测试JavaScript功能

为了测试用JavaScript编写的功能，您可以使用Selenium和PhantomJS等软件在真实浏览器中运行Behat测试。

要为Behat场景启用JavaScript测试，请将@javascript标签添加到测试中，并确保您选择的WebDriver在后台运行。

Chrome

在您的behat.yml.dist文件中设置以下构建属性

# The browser to use for testing, either 'firefox' or 'chrome'.
behat.browser_name = chrome

确保在此更改后重新生成您的Behat配置文件

$ drupal site:behat:setup site_name

您可以在系统上本地安装Selenium和Chrome / Chromium，并使用java -jar selenium-server-standalone.jar启动Selenium。

然而，在Selenium上运行Chrome最简单的方法是使用容器。您可以使用Docker通过单个命令安装和运行它。这将下载所有必要的文件，并以无头模式在后台启动

$ docker run -d -p 4444:4444 --network=host selenium/standalone-chrome

如果您想查看正在运行的浏览器，可以运行“调试”版本，并使用如TigerVNC之类的VNC客户端连接到浏览器（密码为“secret”）

$ docker run -d -p 4444:4444 -p 5900:5900 --network=host selenium/standalone-chrome-debug

有关运行容器化Selenium的更多信息，请参阅SeleniumHQ/docker-selenium。

Firefox

在您的behat.yml.dist文件中设置以下构建属性

# The browser to use for testing, either 'firefox' or 'chrome'.
behat.browser_name = firefox

确保在此更改后重新生成您的Behat配置文件

$ drupal site:behat:setup site_name

您可以在系统上本地安装Selenium和Firefox，并使用java -jar selenium-server-standalone.jar启动Selenium。

然而，在Selenium上运行Firefox最简单的方法是使用容器。您可以使用Docker通过单个命令安装和运行它。这将下载所有必要的文件，并以无头模式在后台启动

$ docker run -d -p 4444:4444 --network=host selenium/standalone-firefox:2.53.1

请注意，Firefox的WebDriver实现（Marionette）在Selenium 3中尚未完成，所以我们指定最新的2.x版本。Selenium 3推出beta版后，这可能会很快完成。

如果您想查看正在运行的浏览器，可以运行“调试”版本，并使用如TigerVNC之类的VNC客户端连接到浏览器（密码为“secret”）

$ docker run -d -p 4444:4444 -p 5900:5900 --network=host selenium/standalone-firefox-debug:2.53.1

有关运行容器化Selenium的更多信息，请参阅SeleniumHQ/docker-selenium。

PhantomJS

PhantomJS是一个基于Webkit的无头浏览器，Webkit与Chrome使用的引擎相同。您可以从包管理器安装它，或者下载它。

在您的behat.yml.dist文件中声明您正在使用类似Chrome的浏览器

# The browser to use for testing, either 'firefox' or 'chrome'.
behat.browser_name = chrome

确保在此更改后重新生成您的Behat配置文件

$ drupal site:behat:setup site_name

现在您可以在WebDriver模式下运行PhantomJS，并运行您的测试。所有标记为@javascript的测试现在将使用PhantomJS执行。

$ phantomjs --webdriver=4444

运行PHPUnit测试

从根目录运行测试

$ ./vendor/bin/phpunit

默认情况下，当运行测试时，会包含web/modules/custom、web/profiles和web/themes/custom文件夹中的所有测试。请检查build.properties.dist中的PHPUnit部分以自定义测试。

检查编码规范违规

设置PHP CodeSniffer

PHP CodeSniffer包含用于检查PHP和JS文件的编码规范。在默认配置中，它将扫描以下文件夹中的所有文件

• web/modules（排除web/modules/contrib）
• web/profiles
• web/themes

首先，您需要执行setup-php-codesniffer Phing目标（注意，这也作为install-dev和setup-dev目标的一部分运行）

$ ./vendor/bin/phing setup-php-codesniffer

这将生成一个包含针对您的本地环境的特定设置的phpcs.xml文件。请确保永远不要提交此文件。

运行编码规范检查

手动运行检查

编码规范检查可以按以下方式运行

# Scan all files for coding standards violations.
$ ./vendor/bin/phpcs

# Scan only a single folder.
$ ./vendor/bin/phpcs web/modules/custom/mymodule

在推送时自动运行检查

为了防止将不符合规范的代码推送到git存储库而尴尬，您可以在您的build.properties.local中放置以下行

# Whether or not to run a coding standards check before doing a git push. Note
# that this will abort the push if the coding standards check fails.
phpcs.prepush.enable = 1

然后重新生成您的PHP CodeSniffer配置

$ ./vendor/bin/phing setup-php-codesniffer

如果您的项目要求所有团队成员遵循编码规范，请将此行放入项目配置（build.properties）中。

请注意，这不会允许您推送任何未通过编码标准检查的代码。如果您真的需要紧急推送，则可以通过执行此Phing目标来禁用编码标准检查。

$ ./vendor/bin/phing disable-pre-push

当执行setup-php-codesniffer目标时，将重新启用预推送钩子。

自定义配置

您可以通过将build.properties.dist中的“PHP CodeSniffer配置”部分的相关Phing属性复制到build.properties中，并根据需要更改它们来更改基本配置。然后通过运行setup-php-codesniffer目标重新生成phpcs.xml文件。

$ ./vendor/bin/phing setup-php-codesniffer

要更改到PHP CodeSniffer规则集本身，复制文件phpcs-ruleset.xml.dist并将其重命名为phpcs-ruleset.xml，然后在您的build.properties文件中添加此行。

phpcs.standard = ${project.basedir}/phpcs-ruleset.xml

有关配置规则集的更多信息，请参阅标注规则集。

常见问题解答（FAQ）

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

Composer建议不要。他们提供了反对的论据，但如果项目决定这样做，也有解决方案。

我如何将补丁应用到下载的模块中？

如果您需要应用补丁（根据要修改的项目，拉取请求通常是一个更好的解决方案），您可以使用composer-patches插件。

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

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