README

快速启动 WordPress 插件的模板。

详细信息

将此项目作为您的模块化 WordPress 插件的起点！

特性

Docker - 使用 Docker 开发和测试您的插件。使用为您的插件量身定制的环境。在浏览器中立即查看更改。构建包含完整 WordPress 安装和所有预置要求的 Docker 镜像。
PHPStorm - 为可能最优秀的 PHP IDE 的集成提供配置，包括
- 数据库客户端 - 在 PHPStorm 中查看和操作数据库。
- Composer - 在 IDE 中安装和管理 PHP 依赖项的正确版本，无需离开 IDE。
- PHPUnit - 在 PHPStorm 中直接运行测试并获取报告。
- xDebug - 在 PHPStorm 中设置断点并检查您的代码。
- 代码覆盖率 - 在友好的 GUI 中查看尚未测试的内容。
静态代码分析 - 保持一致的编码风格，并及早发现问题。
- Psalm - 检查您的代码中的问题。
- PHPCS - 检查您的代码风格。 PHPCBF 可以自动修复其中的一些。
持续集成 - 使用 GitHub Actions 自动验证所有贡献是否符合项目标准。
模块化 - 将关注点分离到模块中，由于 composer-merge-plugin，您可以在任何时间自由地将它们移动出包。
构建脚本 - 使用单个 GNU Make 入口点就地构建插件，包括模块；或者，构建一个 dist 版本，而不影响当前工作目录。

使用方法

入门

使用此模板

此 GitHub 存储库是一个模板。使用它从中创建自己的项目。

当然，您始终可以手动克隆并推送到其他地方，或者使用其他更合适的分支方法。
自定义项目

注意：以下星号 * 表示更改此值需要重建图像以对开发环境产生影响。
- 将 .env.example 复制到 .env。
- .env:
  - PLUGIN_NAME - 您插件的 slug。必须与插件文件夹名称相对应。
  - BASE_PATH - 如果您使用的是 Docker Machine，即在非 Linux 系统上，请将此设置为机器内项目文件夹的绝对路径 内部路径。如果您在 Linux 上，则无需更改。
  - PROJECT_MOUNT_PATH - 将项目文件夹挂载到的路径。这应该是容器内您的插件文件夹的绝对路径。
  - PROJECT_NAME - 您项目的缩写。主要用于使用 container_name 为容器命名。这在同一台机器上运行多个项目时非常有用。
  - PHP_BUILD_VERSION - 插件将构建的 PHP 版本。这应与您插件的最小 PHP 要求相匹配。用于确定 php 镜像的标签。
  - PHP_TEST_VERSION* - 插件将运行的 PHP 版本。这应与您插件的最大 PHP 要求相匹配。用于确定 wordpress 镜像的标签。
  - WORDPRESS_VERSION* - 插件将运行的 WordPress 版本。用于确定 wordpress 镜像的标签。
  - DB_USER_PASSWORD* - 此变量和其它 DB_* 变量用于确定 WordPress 数据库的密码。如果您想保护您的部署应用程序，请更改这些。
  - WP_DOMAIN* - 包含您的插件的 WordPress 应用程序的域名。在其它方面，用于设置本地开发镜像。如果本地，对应于 hosts 文件中使用的别名。此值也用于 PHPStorm 的数据库集成。如果更改此值，必须更新 PHPStorm 的配置。
  - WP_TITLE* - 包含您的插件的 WordPress 应用程序的标题。不需要引号，因为 Docker 不会在此文件中展开变量。在本地开发镜像中自动安装 WordPress 时使用。此值也用于 PHPStorm 的数据库集成。如果更改此值，必须更新 PHPStorm 的配置。
  - ADMIN_USER* - 此变量和其它 ADMIN_* 变量用于在自动使用 WP-CLI 安装 WordPress 时确定 WordPress 管理员详细信息。
- composer.json:
  - name - 您包的名称。
  - description - 您包的描述。
  - authors - 您和/或您公司的详细信息。
  - require - 您项目包和平台要求。如果您的最小要求不同，您可能想更改 PHP 版本。别忘了在 .env 中更新 PHP_BUILD_VERSION。
  - require-dev - 您项目的发展要求。您可能想在这里添加插件以获取相关的 IDE 功能；有关此主题的更多信息，请参阅添加插件。
- Module composer.json：此引导程序使用优秀的 composer-merge-plugin 将模块依赖项与模块一起保持在一起。这允许跟踪哪些依赖项属于哪个模块，检测依赖项不兼容性，并在必要时将模块从包中移出，形成它们自己的包。
  
  模块可以从其他包中安装，或包含在包中。在后一种情况下，它们应该添加到 modules 目录。一个这样的模块，插件的 demo 模块，已经包含在包中。这只是为了演示目的，可以重命名、重新编写，或完全删除。无论如何，请参阅添加模块以获取有关如何配置应用程序将使用哪些模块的更多信息。
  
  重要：将模块作为依赖添加到其他模块中是坏习惯。模块之间不直接交互，而是使用类似DDD的方法，但应用于服务定义，以确保它们尽可能隔离。相反，让应用程序（项目的主要包）依赖其他模块，并在应用程序的主要模块中将它们连接起来。一个模块依赖另一个模块的合法理由是，那个其他模块不一定是作为模块加载的，但其符号在某个地方需要。然而，在这种情况下，重要的是在将其添加为应用程序的依赖项之前不要将其视为模块，而将其视为简单的库。
构建一切
1. 构建环境。
  
  为了开发、构建和测试插件，首先需要一些东西。这些包括：数据库、WordPress核心、PHP、Composer和Web服务器。该项目带有所有这些预先配置，并且必须首先构建Docker服务。
```
docker compose build
```
2. 就地构建插件。
  
  为了使项目源文件产生预期效果，首先必须将它们构建成其运行时版本。这可能包括：安装依赖项、转译、复制或存档文件，以及模块为实现预期效果所需的任何其他操作。同时，一个用于执行项目构建或QA期间执行的各种任务的单一入口点，可以提供对项目的更集中和自动化的控制。
  
  因此，Makefile与项目一起提供，声明了包括构建在内的常用任务的命令。在插件源目录中运行以下命令以构建插件，包括模块：这使得在更改后立即预览和测试更改成为可能。
```
docker compose run --rm build make build
```
  注意：此步骤包括安装声明的依赖项。有关此主题的更多信息，请参阅更新依赖项。
启动开发环境

在终端中运行以下命令。如果您使用Docker Machine，您需要先使用docker-machine start启动它，并使用docker-machine env配置您的环境。
```
docker compose up wp_dev 
```
这将启动仅包含开发环境及其依赖项（目前是数据库）的环境。数据库是一个单独的服务，因为在部署环境中，您可以选择使用不同的数据库服务器。

之后，在您的本地hosts文件中添加一个条目。主机应与.env文件中的WP_DOMAIN值的对应。IP地址是Docker机器的IP地址。在Linux上，这与您的机器在本地网络上的IP地址相同，通常127.0.0.1（localhost）即可工作。如果您使用Docker Machine（在非Linux环境中），请使用docker-machine ip找到它。

现在，您应该能够访问该域名，并看到网站。默认情况下，管理员用户名和密码都是admin，并由.env文件中的ADMIN_USER和ADMIN_PASS变量确定。您的插件应该已经安装并激活，不应安装其他插件。如果不是这样，检查您从docker compose up获得的输出。

如果您使用涉及Docker的PHPStorm集成，例如Composer，您可能会收到“未找到Docker账户”的错误。这是因为PHPStorm要求所有项目中使用的Docker部署配置名称相同，目前似乎没有将其提交到VCS的方法。因此，您需要自己创建Docker部署。只需转到项目设置 > Docker，并创建一个名为“Docker Machine”的配置。
发布

当您想要将当前工作目录作为可安装的插件存档发布时，需要执行一些转换（如优化生产依赖项），并以特定方式存档包。以下命令将在build/release中添加一个类似plugin-0.1.1-beta21+2023-08-12-12-37-22_105188ec9180.zip的存档
```
 docker compose run --rm build make release RELEASE_VERSION=0.1.1-beta21
```
如您所见，最终存档的名称将反映版本、时间和提交哈希，作为SemVer元数据，而不仅仅是版本本身。如果省略了RELEASE_VERSION，则默认使用dev来表示这不是一个标记的里程碑，而是工作进展。

注意：如果当前工作目录包含任何Git可以注册的编辑（忽略任何.gitignore规则），则提交哈希将反映build/dist中文件的历史时刻，而不是项目的历史。为确保发布的是具体版本，请完全清理目录树。最好的方法可能是创建一个全新的克隆。

更新依赖项

Composer已安装到build服务的镜像中。要运行Composer命令，请使用docker compose run。例如，要更新依赖项，可以运行以下命令

docker compose run --rm build composer update

如果您使用PHPStorm，可以使用Composer集成，因为项目已经为此进行了配置。

注意：如果PHPStorm没有自动为Composer分配PHP解释器，请将其设置为使用“构建”解释器。所有构建任务，包括依赖项安装，都必须在build服务中运行，这对应于该解释器。

不要为模块的composer.json文件运行composer update！所有Composer操作都必须在根包的composer.json文件上执行。

任何对项目文件夹的更改都会立即反映在开发环境中，这包括vendor文件夹和composer.lock文件。这是因为项目文件夹被挂载到WordPress容器中的正确位置。

添加模块

这个模板支持模块化，并支持开箱即用的Dhii模块。任何暴露ModuleInterface实现的此类模块都可以加载，允许它在应用程序中运行，并使其服务可用。

由src/modules.php返回的模块列表是应用程序中模块的权威来源。因为它是一个PHP代码，所以模块可以以任何所需的方式加载，包括

简单实例化一个将被自动加载的模块类。

如果您的模块类在例如Composer注册的自动加载路径之一，您可以像任何其他类一样实例化它。这是一个加载一些模块的非常快速简单的方法。
使用工厂类或文件。

为了使模块与应用程序解耦，但仍然能够从应用程序向模块提供依赖项，有时希望在应用程序和模块初始化之间使用“填充”。因此，在使用此引导程序的项目中，您有时可能会找到一个module.php文件。此文件返回一个函数，该函数接收一些参数，例如根项目路径，并将返回一个ModuleInterface实例。另一种方法可能是使用命名构造函数，甚至是一个专门的工厂类。
扫描某些路径。

如果模块之间没有任何冲突，模块加载顺序可能无关紧要。在这种情况下，可以通过例如扫描某些文件夹中的某些入口点或配置文件来自动发现模块。实现您想要的任何自动发现机制，只要模块实例最终进入权威列表即可。

外部模块

要从另一个包添加模块，请使用Composer要求该包，并将ModuleInterface实例添加到列表中。

本地模块

要添加本地模块，将模块添加到modules文件夹中，并像对任何其他模块一样执行相同的操作。本地模块还可以通过在根文件夹中添加一个composer.json文件来声明它们自己的依赖项。这些文件将在项目根目录中更新依赖项时被Composer拾取，归功于composer-merge-plugin，前提是在执行composer update之前运行composer update --lock。这是一种将模块依赖项与其他依赖项分离的好方法。有关更多信息，请参阅该Composer插件的文档。

添加插件

如果您的插件依赖于或可以与其他插件集成，您可能希望将它们添加到环境中。为了获得诸如其他插件代码自动建议之类的IDE功能，您可能希望将它们添加到您的require-dev中。

为了使测试WordPress网站安装并激活另一个插件，将适当的WP-CLI命令添加到docker/wp-entrypoint.sh脚本中。示例

wp plugin install bbpress --version=2.6.9 --activate --allow-root --path="${DOCROOT_PATH}"

请注意

需要--allow-root标志，因为这将由Docker以超级用户身份运行。
还需要--path选项，并且必须设置为$DOCROOT_PATH，以确保所有工具都在同一路径上工作。您还可以在此文件中使用其他来自.env的变量，只要它们配置为通过docker-compose.yml传递到服务中。
--activate标志会在安装后激活插件。

QA

通过使用包含的Makefile中的qa目标一次性运行所有QA工具。所有QA都在test服务中完成。

docker compose run --rm test make qa

测试代码

使用test目标一次性运行所有测试。

docker compose run --rm test make test

PHPUnit

此引导程序包括PHPUnit。它已经配置好，您可以通过运行示例测试来测试它是否正常工作
```
docker compose run --rm test make test-php
```
- 也会在CI上自动运行。
- 包括PHPStorm 集成。

静态分析

通过使用scan目标一次性运行所有静态分析工具。

docker compose run --rm test make scan

Psalm

在项目根目录中运行Psalm
```
docker compose run --rm test vendor/bin/psalm
```
- 也会在CI上自动运行。
- 包括PHPStorm 集成。
PHPCS

在项目根目录中运行PHPCS/PHPCBF
```
docker compose run --rm test vendor/bin/phpcs -s --report-source --runtime-set ignore_warnings_on_exit 1
docker compose run --rm test vendor/bin/phpcbf
```
- 默认情况下，使用PSR-12和来自Slevomat Coding Standard的一些规则。
- 也会在CI上自动运行。
- 包括PHPStorm 集成。

调试

该引导程序在Docker环境的test服务以及PHPStorm配置中包含了xDebug。要使用它，在tests目录下的任何测试或文件夹上右键单击，然后选择“调试”。这将启用xDebug运行测试。如果您收到关于xdebug.remote_host设置错误的信息，并建议修复错误，请通过在弹出的窗口中将该变量设置为您的计算机的IP地址（在本地网络中）来修复它。之后，在PHPUnit测试可达的任何代码中的断点（包括测试本身的代码）将导致执行暂停，以便检查代码。

如果您更改了test服务的PHP版本，调试器将停止工作。这是因为不同的PHP版本使用不同的xDebug版本，并且因为xDebug扩展的路径取决于其版本，所以该路径也将改变，从而使当前配置的路径无效。要修复此问题，需要更新解释器设置屏幕中的“调试器扩展”字段。您可以通过运行docker compose run test ls -lah /usr/local/lib/php/extensions来查看扩展列表。其中之一可能类似于no-debug-non-zts-20170718。将“调试器扩展”路径值的对应部分更改为该字符串。

目前，无法检查在网络请求期间运行的代码。

数据库UI

该引导程序已准备好配置PHPStorm的数据库集成。要使用它，其设置必须与DB_USER_PASSWORD的值一致。使用它强烈推荐，因为它是一个集成的DB客户端，将在编码期间提供帮助。

或者，您也可以安装和配置一个phpMyAdmin服务或类似的。

wp-oop / plugin-boilerplate

维护者

详细信息

README

详细信息

特性

使用方法

入门

更新依赖项

添加模块

外部模块

本地模块

添加插件

QA

测试代码

静态分析

调试

数据库UI