README

开始使用

一行安装

composer create-project wppunk/wpplugin your-plugin-directory

或者您也可以复制归档或通过Git克隆，然后运行

composer init-project

需求

确保在继续之前已安装所有依赖项

• WordPress
• PHP >= 7.2.5 (您可以轻松降级它)
  • DOM 扩展
  • CURL 扩展
• Composer
• Node.js >= 14.8
• npm
• ChromeDriver (用于验收测试)

结构

plugins/your-awesome-plugin/        # → Root of your plugin.
├── .codeception/                   # → Codeception additional directories.
│   ├── _config/                    # → Configs for DB connection.
│   ├── _data/                      # → Folder for SQL dump.
│   └── _support/                   # → Additional classes for the Codeception tests.
├── .github/                        # → GitHub additional directories.
│   └── workflows/                  # → Workflows.
│       ├── plugin-name.conf        # → Config for the server.
│       └── plugin-name.yml         # → Actions for GitHub.
├── .tests/                         # → Tests.
│   └── php                         # → PHP tests.
│       ├── acceptance              # → PHP Acceptance tests.
│       ├── unit                    # → PHP Unit tests.
│       │   └── _bootstrap.php      # → Bootstrap file for PHP unit tests.
│       ├── acceptance.suite.yml    # → Config file for the acceptance tests.
│       └── unit.suite.yml          # → Config file for the unit tests.
├── assets/                         # → Assets directory.
│   ├── build/                      # → Assets build directory.
│   └── src/                        # → Assets source directory.
├── node_modules/                   # → JS packages (never edit).
├── src/                            # → PHP directory. 
├── templates/                      # → Templates for plugin views.
├── vendor/                         # → Composer packages (never edit).
├── vendor_prefixes/                # → Prefixed composer packages for non-conflict mode (never edit).
├── .codeception.yml                # → Main codeception config.
├── .env.example                    # → Example for the .env.development and .env.production files
├── .eslintignore                   # → JS Coding Standards ignore file.
├── .eslintrc.js                    # → JS Coding Standards config.
├── .gitconfig                      # → Config for git.
├── .gitignore                      # → Git ignore file.
├── .phpcs.xml                      # → Custom PHP Coding Standards.
├── .scoper.inc.php                 # → Config for the PHP Scoper.
├── .stylelintrc                    # → Config for the style linter.
├── .webpack.mix.js                 # → Laravel Mix configuration file.
├── CHANGELOG.md                    # → Changelog file for GH.
├── composer.json                   # → Composer dependencies and scripts.
├── composer.lock                   # → Composer lock file (never edit).
├── LICENSE                         # → License file.
├── package.json                    # → JS dependencies and scripts.
├── package-lock.json               # → Package lock file (never edit).
├── plugin-name.php                 # → Bootstrap plugin file.
├── README.md                       # → Readme MD for GitHub repository.
├── readme.txt                      # → Readme TXT for the wp.org repository.
└── uninstall.php                   # → Uninstall file.

自动加载

我们使用 PSR-4 和 composer 自动加载。您可以在 composer.json 文件中的 autoload 指令中找到它。

编码规范

检查所有编码规范

npm run cs

PHP 编码规范 (PHPCS)

我们使用基于 WordPress 编码规范 的自定义编码规范。由于使用 PSR-4 自动加载，我们禁用了 WordPress 文件命名的规则。此外，我们还有一个 功能，允许您使用不同的 PHP 环境测试您的代码。

您可以在 .phpcs.xml 中找到自定义 PHPCS。

您可以使用 CLI 检查 PHPCS

composer cs

或

npm run cs:php

请注意，测试有一些不同的编码规范，因为测试库所有都使用 camelCase 格式为方法、函数、变量和属性。

在每次提交、推送和 GH Actions 之前检查 PHPCS。

JS 编码规范 (JSCS)

我们使用默认的 WordPress JSCS，但您可以在 .eslintrc 文件中修改它。

您可以使用 CLI 检查 JSCS

npm run cs:js

SCSS 编码规范 (SCSSCS)

我们使用默认的 SCSS 规范，但您可以在 .stylelintrc 文件中修改它。

您可以使用 CLI 检查 SCSSCS

npm run cs:scss

环境

对于任何常量，您可以创建 .env.development 和 .env.production 文件。例如，我们使用这些常量从 .env.example 文件中的 Laravel Mix 配置中的浏览器同步以及验收测试。

前端

所有资产都位于 assets/src/*。

所有构建都位于 assets/build/*。

CSS 预处理器是 SCSS。

我们使用 Laravel Mix 进行资产构建。您可以在 .webpack.mix.js 文件中修改它。

根据情况，您可以使用以下命令运行 Laravel mix

npm run build
npm run build:production
npm run start

GitHub

GH Actions

您可以在 .github/workflows/plugin-name.yml 文件中找到 GH Actions 的所有步骤。此外，为了唤醒 Web 服务器，我们需要添加 .github/workflows/plugin-name.conf

GH Hooks

只需确保您的 GH 存储库清晰。我们使用 Husky 库在提交、推送等之前添加操作。这有助于开发者使他们的 GH 更清晰。

GH 模板

基本的 GH 模板，以提高安全问题、支持请求、错误报告、增强、功能请求、拉取请求和贡献模板的安全性。

依赖注入容器

轻量级的 依赖注入 组件实现了 PSR-11 兼容的服务容器，允许您标准化并集中管理应用程序中对象的构建方式。

使用类型提示自动加载您的依赖项。

您可以使用DIC（依赖注入容器）非常容易地禁用插件钩子。只需从依赖注入容器中获取插件对象 $container_builder->get(PluginName\Front\Front::class)。例如，仅禁用前端资源

function remove_plugin_name_frontend_assets( $injector ) {
    $front = $injector->make( PluginName\Front\Front::class );
    if ( ! $front ) {
        return;
    }
    remove_action( 'wp_enqueue_scripts', [ $front, 'enqueue_styles' ] );
    remove_action( 'wp_enqueue_scripts', [ $front, 'enqueue_scripts' ] );
}

add_action( 'plugin_name_init', 'remove_plugin_name_frontend_assets' );

PHP Scoper

您需要为每个外部依赖项添加前缀，因为其他插件或主题可能会使用相同的依赖项，这可能导致包之间冲突。

composer scoper

自动化测试

我们使用Codeception库进行自动化测试，它运行所有类型的PHP测试。

PHP单元测试

运行时使用CLI命令

composer unit

• 主配置文件 .tests/php/unit.suite.yml
• 单元测试位于 .tests/php/unit/* 文件夹中。
• 引导文件 .tests/php/unit/_bootstrap.php
• 测试类文件的每个名称都必须以 *Test.php 为后缀。
• 每个测试类都必须扩展 PluginNameUnitTests\TestCase 类。
• 您还可以在 PluginNameUnitTests\TestCase.php 中添加一些代码。
• 每个测试方法都必须以 test_ 为前缀。
• 测试运行时自动加载的附加文件可以添加到 .codeception/_support/* 文件夹中。

此外，单元测试将在推送仓库动作和GH Actions管道中进行检查。

PHP验收测试

警告！验收测试会在您的网站上执行真实操作。在运行之前，需要创建另一个数据库并创建一个包含最新WP安装的 dump.sql 文件。

在运行之前，您需要（只需要做一次。希望您能完成）

1. 安装 ChromeDriver
2. 创建一个新的数据库。例如，我命名数据库为 codeception_db
3. 安装一个清晰的WordPress
4. 将数据库导出到 dump.sql
5. 将 dump.sql 文件移动到 .codeception/_data/ 文件夹。
6. 将文件 .codeception/_config/params.example.php 复制到 .codeception/_config/params.local.php。
7. 在 .codeception/_config/params.local.php 文件中更新您的测试站点连接信息。
8. 更新您的 wp-config.php 文件

if ( 
    isset( $_SERVER['HTTP_X_TESTING'] )
    || ( isset( $_SERVER['HTTP_USER_AGENT'] ) && $_SERVER['HTTP_USER_AGENT'] === 'wp-browser' )
    || getenv( 'WPBROWSER_HOST_REQUEST' )
) {
    // Use the test database if the request comes from a test.
    define( 'DB_NAME', 'codeception_db' );
} else {
    // Else use the default one (insert your local DB name here).
    define( 'DB_NAME', 'local' );
}

运行时使用CLI命令

composer acceptance

• 主配置文件 .tests/php/acceptance.suite.yml
• 验收测试位于 .tests/php/acceptace/* 文件夹中。
• 测试类文件的每个名称都必须以 *Cest.php 为后缀。
• 每个测试方法都必须以 test_ 为前缀。
• 每个测试方法都必须包含 AcceptanceTester 作为参数。
• 您可以在 .codeception/_support/AcceptanceTests.php 中为 AcceptanceTester 添加一些方法。
• 测试运行时自动加载的附加文件可以添加到 .codeception/_support/* 文件夹中。

JS单元测试

运行时使用CLI命令

npm run unit

• 主配置位于 jest 目录下的 .tests/js/package.json 中。
• 单元测试位于 .tests/js/unit/* 文件夹中。
• 引导文件 .tests/js/setupTests.js
• 测试类文件的每个名称都必须以 *.test.js 为后缀。
• 仅导入您的测试类并编写测试。

此外，单元测试将在推送仓库动作和GH Actions管道中进行检查。