README

此项目可快速开始新的Drupal项目。它包含所有常用的QA工具，如PHPStan或Psalm，如果您想从完全配置的系统开始，还包括数据库转储。

此README是您项目的起点，但不一定是项目模板的一部分。

目录

• 系统要求
• 登录
• 变更日志
• 文档
• 设置
• 在项目中工作
• 更新Drupal
• 包含的二进制文件
• 常见问题
• 许可证
• 贡献
• 致谢
• 联系方式
• 项目状态

系统要求

• PHP >= 8.3
• MySQL >= 8或MariaDB >= 10.2
• Apache >= 2.4或Nginx >= 1.15
• Composer >= 2.0
• Node.js >= 16.0
• npm >= 7.0
• bun >= 1.0
• Git >= 2.0

服务器要求

• PHP扩展
  • ctype
  • curl
  • date
  • dom
  • filter
  • gd
  • hash
  • json
  • libxml
  • mbstring
  • openssl
  • pcre
  • pdo
  • phar
  • session
  • simplexml
  • spl
  • tokenizer
  • xml
  • xmlwriter
• RAM：最小256MB，推荐512MB
• 磁盘空间：最小1GB，推荐2GB
• Apache模块
  • mod_rewrite
• CPU：最小2核心，推荐4核心
• Plesk或类似服务器非常推荐
• SSH访问

推荐服务器

• dogado Cloud Server M 4.0（或更高版本）

用于本地开发

• Docker（桌面）>= 4.19
• Git >= 2.0
• Node.js >= 18.0
• npm >= 7.0
• bun >= 1.0

推荐

• PHP >= 8.3
• Composer >= 2.0

登录

以下列出的密码是默认账户的默认密码。第一步应该是更改每个账户的密码。

通过/user/login或/user（在后一种情况下，如果您尚未登录，将被重定向）登录。

变更日志

您可以在文件CHANGELOG.md中找到变更日志，该文件位于CHANGELOG.md。

文档

您可以在本README文件以及docs目录中找到文档。

设置

如果您正在处理现有项目，您可以跳过此部分。或者，您也可以从客户项目文档中删除此部分，因为它不再需要。

要求

• Lando
• Composer* >= 2.0.0
• PHP* >= 8.1

* 如果您想在本地运行像composer install这样的命令，则必需。使用Lando，您也可以通过在命令前添加lando来在Lando内部运行此类命令。

1. 复制仓库

使用Composer的方式意味着您使用composer create-project命令安装项目模板。

您可以在终端中运行以下命令来创建项目

$ composer create-project boatware/drupal-project PROJECT_NAME

通过此步骤，您可以跳过步骤2，因为create-project命令将安装依赖项并为您运行bin/setup二进制文件。

2. 安装依赖项

要在终端中安装所有依赖项，请运行以下命令

$ composer install

在创建新项目时，此命令还将运行二进制文件bin/setup，它将为您执行一些设置步骤。之后，您可以删除该文件，因为以后将不再使用它。

3. 解压媒体文件

要解压媒体文件，请在您的终端中运行以下命令

$ tar -xzf sites-default-files.tar.gz

此命令将预存文件放入正确的目录。

4. 设置环境

为了运行项目，您至少需要提供数据库凭据。

为此，此模板提供了一个.env文件，它应该已经被bin/setup命令创建。如果没有，您可以手动创建它，方法是复制.env.example文件。

默认凭据如下

# Database credentials
MYSQL_HOSTNAME='database'
MYSQL_USER='drupal10'
MYSQL_PASSWORD='drupal10'
MYSQL_DATABASE='drupal10'
MYSQL_PORT='3306'

如果您选择使用另一个环境，例如Homestead，则需要根据您的开发环境调整这些值。

5. 设置Lando（可选）

如果您不使用Lando作为开发环境，则可以跳过此步骤。

在您第一次启动Lando之前，您需要调整.lando.yml文件中的项目名称。按照惯例，您可以使用您所在的目录命名它。

6. 设置部署

由于您在新鲜安装后首先要做的事情是设置部署。这样我们就不需要在存储库中存储任何数据库备份。

要设置部署，如果存在，请删除文件deploy.php，然后将文件deploy.dist.php复制到deploy.php，并根据您的需求调整值。

⚠️ 请务必在完成后检查deploy.php文件！项目模板已设置为部署到其自己的主机。

7. 启动环境

要启动环境，请在您的终端中运行以下命令

$ make start

8. 安装Drupal

从提供项目当前状态的服务器获取当前数据库备份，并将其导入到您的本地数据库。您可以在终端中运行以下命令来完成此操作

$ docker compose run --rm database mysql -udrupal -pdrupal drupal < DUMPFILE.sql

请确保通过在终端中运行以下命令来应用最新的配置更改

$ bin/drush cim

然后通过在终端中运行以下命令来清除缓存

$ bin/drush cr

这确保了配置是最新的，因为数据库备份可能有点过时。

9. 下载文件目录

为了在本地环境中获取导入内容的上传媒体文件，通过SSH登录到服务器，并在终端中运行以下命令

$ cd PROJECT_ROOT && tar -czf files.tar.gz web/sites/default/files

其中PROJECT_ROOT是项目根目录的路径（不是文档根/web）。

然后将其下载到您的本地计算机并解压。

执行此操作的一种方法是在终端中运行以下命令

$ scp USER@HOST:PATH/TO/files.tar.gz .
# e.g. scp user@host:/path/to/files.tar.gz .

其中USER是SSH用户，HOST是SSH主机，PROJECT_ROOT是项目根目录的路径（不是文档根/web）。

然后通过在终端中运行以下命令来解压文件

$ tar -xzf files.tar.gz

请务必在完成后删除服务器和本地计算机上的files.tar.gz文件。

10. 后期维护

安装完成后，您可以将新创建的项目部署到预发布服务器。为了正常工作，您需要遵循以下步骤

• 设置预发布环境（数据库、Web服务器等）
• 通过lando drush cex从本地环境导出配置
• 通过lando db-export从本地环境导出数据库
• 将数据库导入到预发布环境中
• 将文件目录上传到预发布环境

现在您可以通过运行以下命令来部署项目

$ vendor/bin/dep deploy stage

您可能还想执行的一些其他步骤

• 从README中删除此设置部分
• 将以下部分重命名为“设置”
• 将PROJECT_URL替换为存储库的实际SSH URL

设置（现有项目）

要求

• Lando
• Composer* >= 2.0.0
• PHP* >= 8.1

* 如果您想在本地运行像composer install这样的命令，则必需。使用Lando，您也可以通过在命令前添加lando来在Lando内部运行此类命令。

1. 复制仓库

要获取项目的最新版本，首先创建一个新的目录

$ mkdir PROJECT_NAME

然后将项目克隆到当前目录，请在终端执行以下命令

$ git clone PROJECT_URL PROJECT_NAME

2. 安装依赖项

要在终端中安装所有依赖项，请运行以下命令

$ composer install

3. 设置环境

为了运行项目，您至少需要提供数据库凭据。

为此，复制 .env.example 文件并将其重命名为 .env。然后根据您的需求调整值。

默认凭据如下

# Database credentials
MYSQL_HOSTNAME='database'
MYSQL_USER='drupal10'
MYSQL_PASSWORD='drupal10'
MYSQL_DATABASE='drupal10'
MYSQL_PORT='3306'

当在 Lando 之外的环境中工作时，您需要根据您的开发环境调整这些值。

4. 启动 Lando

要启动 Lando，请在终端运行以下命令

$ lando start

第一次启动可能需要一段时间，因为 Lando 需要构建容器，所以可以去喝杯咖啡。

5. 导入数据库

如果系统已部署到任何位置，获取数据库转储

• 如果系统已部署到生产环境，从那里获取数据库
• 如果系统已部署到测试环境，从那里获取数据库
• 如果系统尚未部署，请参阅文档或询问设置此项目的开发者

然后在您的本地环境中运行以下命令以导入数据库

$ lando db-import DATABASE_DUMP

6. 导入配置

确保您的环境中包含最新的配置更改，请在终端运行以下命令

$ lando drush cim

7. 清除缓存

为确保一切正常工作，请在终端运行以下命令清除缓存

$ lando drush cr

8. 验证环境

为了完成本地设置，您应该检查以下内容

• 项目运行在正确的 URL 上（默认以 .lndo.site 结尾）
• 您可以使用默认凭证（admin / admin 或在 Keeper 中存储的凭证）登录
• 您可以访问管理区域
• 在 web/sites/default 目录中有一个名为 settings.local.php 的文件
• web/sites 目录中的 development.services.yml 文件包含以下内容

parameters:
  http.response.debug_cacheability_headers: true
  twig.config:
    debug: true
    auto_reload: true
    cache: false

在项目中工作

在处理项目时，您应遵循某些约定以确保一切正常工作，并保持我们的标准。

提交消息

提交消息应使用英文并遵循 常规提交 标准。

例如

feat: add new feature

如果您正在处理 Jira 工单或 GitHub 问题，应在提交消息中引用工单

feat: add new feature (ISSUE-123)

分支名称

分支名称应使用英文并遵循 Gitflow 标准。

一些注意事项

• 当将 develop 合并到 main 时，所有 合并到 develop 的功能将在之后部署到生产环境中（或者至少已准备好部署）。这种行为可能与客户的期望冲突，因此请确保与客户沟通这一点。客户可能期望只部署功能 A 到生产环境，但在内部测试功能 B。客户需要知道功能 B 也会部署到生产环境中。为了防止这种情况，您需要为功能 B 创建一个软件开关（例如创建一个配置）并在生产环境中禁用它。

Drupal 编码标准

请确保遵循 Drupal 编码标准。您可以在终端中运行以下命令来检查您的代码（在本地或从您的环境中运行）

$ bin/phpcs

命名约定

• 为单个项目制作的模块以客户的姓名开头（例如 customer_xy_ 或 mysite_）
• 主题和配置文件也是如此

结构约定

模块

• 模块应放置在 web/modules/custom 目录中（只有通过 Composer 加载的模块才会放置在 web/modules/contrib）
• 服务应放置在命名空间 Drupal\PROJECT_NAME\Service 中 - 因此需要一个 web/modules/custom/PROJECT_NAME/src/Service 目录
• 控制器应放置在命名空间 Drupal\PROJECT_NAME\Controller 中 - 因此需要一个 web/modules/custom/PROJECT_NAME/src/Controller 目录
• 表单应放置在命名空间 Drupal\PROJECT_NAME\Form 中，因此需要创建一个目录 web/modules/custom/PROJECT_NAME/src/Form
• 经验法则：将类放置在其类型的目录中，例如服务类放置在 web/modules/custom/PROJECT_NAME/src/Service/MyService.php，控制器类放置在 web/modules/custom/PROJECT_NAME/src/Controller/MyController.php

主题

• 主题应放置在 web/themes/custom 目录中（只有通过 Composer 加载的主题才会放置在 web/themes/contrib）
• 为了自动化，如果前端代码需要一些额外的处理（例如编译 SCSS 到 CSS），你应在 package.json 文件的 scripts 部分提供一个入口

类

• 控制器仅用于路由请求，任何逻辑都应放置在服务中
• 尽可能使用依赖注入（你需要这样做，以便遵循 Drupal 最佳实践编码标准）
• 避免使用单体类和方法，将代码拆分为多个类和方法，使其更易于阅读和维护。这样，你遵循了 单一职责原则 和 开放/封闭原则
• 实体类应具有每个定义字段的获取器和流畅设置器。在 Drupal 中，这比在 Symfony 中要困难一些，但这样可以确保你不必查找任何字段名称，而是可以利用 IDE 的自动完成功能。

提交频率

经常提交并尽早提交。这样你可以轻松回滚更改，并且可以轻松追踪错误。

变更日志

每次添加、更改或替换内容时，请确保添加一个变更日志条目。这样你可以轻松追踪更改并将它们传达给客户。

你应该遵循 Keep a Changelog 标准。

重要：不要为每个提交添加条目。相反，为每个实际更改添加条目。你可能在一个或多个提交中进行了添加、删除或更改，但你只需在变更日志中添加一个条目。

更新Drupal

要更新 Drupal 核心、所有贡献项目（模块、主题等）及其依赖项，你可以选择半自动方式运行单个命令，或者选择手动方式逐个运行所有必要的命令。

半自动

要将 Drupal 更新到最新次要版本，请在您的终端中运行以下命令

make update

此命令执行与手动方式相同的命令，但仅在一个命令中。

手动

注意：以下所有命令都使用 docker compose run 命令。如果您更喜欢在本地机器或任何其他设置上执行此操作，请根据您的需求调整命令。

要更新 Drupal，您需要通过在终端中执行以下命令来获取 Drupal 核心和所有贡献项目的最新兼容版本

$ docker compose run --rm php composer update --with-all-dependencies

下一步是运行以下命令更新数据库

$ docker compose run --rm php drush updb

由于数据库更新可能会更改配置文件，您需要运行以下命令导出配置

$ docker compose run --rm php drush cex

最后，您只需运行以下命令清除缓存

$ docker compose run --rm php drush cr

现在您可以检查项目中的任何错误，提交每个更改的文件，并推送更新。

包含的二进制文件

以下所有二进制文件都位于 ./bin。

lint-php - PHP 检查器

检查 ./web/modules/custom 和 ./web/themes/custom 目录中的所有 PHP 文件以查找语法错误。

用法

$ bin/lint-php

phpcs - PHP 代码检查器

检测 ./web/modules/custom、./web/themes/custom 和 ./web/profiles/custom 目录中的代码风格和格式问题。

正在使用的标准是 Drupal 编码规范。有关更多信息，请参阅 Drupal 编码规范。

用法

要检查问题，请在您的终端中运行以下命令

$ bin/phpcs

phpstan - PHP 静态分析工具

检测 ./web/modules/custom、./web/themes/custom 和 ./web/profiles/custom 目录中的可能错误。

使用的级别是 8。有关更多信息，请参阅 配置。

用法

$ bin/phpstan

常见问题

1. 在 deploy:lock 步骤中，Deployer 抛出错误

错误信息如下

$ vendor/bin/dep deploy <HOST>
task deploy:info
[stage] info deploying develop
task deploy:lock
[stage]  error  in lock.php on line 9:
[stage] run [ -f <DEPLOY_PATH>/.dep/deploy.lock ] && echo +locked || echo 'YOUR NAME' > <DEPLOY_PATH>/.dep/deploy.lock
[stage] err bash: line 1: <DEPLOY_PATH>/.dep/deploy.lock: No such file or directory
[stage] exit code 1 (General error)
task deploy:failed
task deploy:unlock

当服务器上不存在 deploy.lock 文件时，会出现此情况。要修复此问题，请确保在部署时执行 deploy:prepare 步骤。此步骤确保目录结构和 deploy.lock 文件可以被创建。

2. 在 deploy:update_code 步骤中，Deployer 抛出错误

错误信息如下

The command "git archive --remote GIT_URL --format tar BRANCH | (cd DEPLOYMENT_DIR && tar xf -)" failed.

  Exit Code: 2 (Misuse of shell builtins)

  Host Name: stage

  ================
  Permission denied, please try again.
  Permission denied, please try again.
  Permission denied (publickey,gssapi-keyex,gssapi-with-mic,password).
  fatal: The remote end hung up unexpectedly

当出现此错误时，可能有以下原因之一

• 您的 SSH 密钥尚未添加到服务器
  • 要修复此问题，请在您的终端中运行以下命令将您的 SSH 密钥添加到服务器

  $ ssh-copy-id <SSH_USER>@<SSH_HOST>

• 您的 SSH 密钥尚未添加到 GitLab/GitHub 等实例
  • 要修复此问题，请访问您使用的 Git 主机设置中的 SSH 密钥部分，并添加您的 SSH 密钥
• 您正在 Mac 上工作，且 SSH 密钥尚未添加到密钥链
  • 要修复此问题，请在您的终端中运行以下命令将您的 SSH 密钥添加到密钥链

  $ ssh-add --apple-use-keychain

许可证

由于 Drupal 本身是根据 GNU 通用公共许可证 许可的，因此该项目也是基于同一许可证。

贡献

致谢

联系方式

项目状态

(c) 2024 Thomas Artmann