README

⚠️ 此项目不再维护或支持！

此工具集是在还没有可靠方式通过Composer和npm引入开发者工具之前创建的。我们现推荐通过将每个工具添加为开发依赖项来添加代码检查和测试支持。

常用工具，用于促进WordPress主题和插件的开发和测试。

非常适合添加编码标准、代码检查和自动测试，即使是旧项目也能受益，因为默认情况下只对新代码应用检查。

安装
配置
- 建议的Composer包
自动化
- 使用Git Hooks本地操作
- Travis CI
预提交提示
环境变量
PHPUnit代码覆盖率
Codeception
Gitter
插件辅助工具
贡献
鸣谢

安装

使用 npm

npm install --save-dev xwp/wp-dev-lib

它将被放置在 node_modules/xwp/wp-dev-lib 下。通过将其附加到包名 xwp/wp-dev-lib#1.2.3 来锁定到特定的发布版本号，其中 1.2.3 是版本号。

作为 Git Submodule

git submodule add -b master https://github.com/xwp/wp-dev-lib.git dev-lib

以更新库的最新更改

git submodule update --remote dev-lib
git add dev-lib
git commit -m "Update dev-lib"

配置

此工具附带以下代码检查器的示例配置文件

将所需的文件复制到您项目的根目录。

将各种工具作为项目的依赖项安装，并锁定到所需的特定版本，是一种最佳实践。这将确保工具在各个环境中可重复安装。当本地安装工具时，将使用它而不是任何全局安装的版本。

建议的 Composer 包

将这些作为开发依赖项添加到您的项目中

composer require --dev package/name

wp-coding-standards/wpcs 用于添加 WordPress 编码标准检查。与示例 phpcs.xml 配置一起使用。
phpcompatibility/phpcompatibility-wp 用于检查 PHP 兼容性。使用 composer.json 文件中指定的 PHP 版本要求。例如 composer require php '>=5.2'。
dealerdirect/phpcodesniffer-composer-installer 用于自动配置 PHP_CodeSniffer 编码嗅探器。

自动化

本地使用 Git 钩子

此工具附带一个 pre-commit 钩子，在每次提交您的项目之前都会运行所有代码检查、测试和检查。

要使用 Composer 添加钩子，我们建议使用 brainmaestro/composer-git-hooks

composer require --dev brainmaestro/composer-git-hooks

并在 composer.json 中添加以下配置

{
  "extra": {
    "hooks": {
      "pre-commit": "./vendor/xwp/wp-dev-lib/scripts/pre-commit"
    }
  }
}

以及两个额外的脚本，在 composer install 期间自动设置钩子

{
  "scripts": {
    "post-install-cmd": [
      "vendor/bin/cghooks add --no-lock"
    ],
    "post-update-cmd": [
      "vendor/bin/cghooks update"
    ],
  }
}

使用 npm，我们建议使用 husky

npm install husky --save-dev

并在您的 package.json 中添加以下脚本

{
  "scripts": {
    "precommit": "./node_modules/wp-dev-lib/scripts/pre-commit"
  }
}

或者，创建一个指向 pre-commit 的符号链接，使用捆绑的脚本

./vendor/xwp/wp-dev-lib/scripts/install-pre-commit-hook.sh

为了确保您的团队中的每个人都自动添加了 pre-commit 钩子，我们建议使用上面描述的 Composer 或 npm 脚本，因为包管理器将在安装阶段设置 pre-commit 钩子。

Travis CI

将 sample-config/.travis.yml 文件复制到您的存储库根目录

cp ./vendor/xwp/wp-dev-lib/sample-config/.travis.yml .

请注意，此配置文件中的大部分逻辑都位于 travis.install.sh、travis.script.sh 和 travis.after_script.sh 中。

编辑 .travis.yml 以更改需要测试的目标 PHP 版本和 WordPress 版本，以及是否需要测试多站点

php:
  - 5.3
  - 7.0

env:
  - WP_VERSION=latest WP_MULTISITE=0
  - WP_VERSION=latest WP_MULTISITE=1
  - WP_VERSION=trunk WP_MULTISITE=0
  - WP_VERSION=trunk WP_MULTISITE=1

这里有多样性对于开源插件来说是有好处的，开源插件对 Travis CI 是免费的。然而，如果你使用私有仓库的 Travis CI，你可能想限制必要的作业以完成构建。所以如果你的生产环境正在运行 PHP 5.5，处于 WordPress 的最新稳定版本，并且不是多站点，那么你的 .travis.yml 可以是这样的

php:
  - 5.5

env:
  - WP_VERSION=4.0 WP_MULTISITE=0

这将大大加快构建时间，让你更快地获得拉取请求状态的反馈，并防止 Travis 构建队列过载。

预提交提示

linters 的默认行为是只报告提交中实际处于暂存状态的更改行上的错误。所以请记得有选择性地暂存文件（通过 git add ...）或者更好的是补丁（通过 git add -p ...）。

跳过检查

如果你需要出于特殊情况（例如，为了提交一个工作成果以供共享）禁用 pre-commit 钩子，可以使用 --no-verify 参数

git commit --no-verify -m "WIP"

或者，你也可以通过 DEV_LIB_SKIP 环境变量有选择性地禁用 pre-commit 钩子的一些方面。例如，当有 PHP 文件的更改，并且一个仓库中包含了 PHPUnit 测试，但你只是更改了一个 PHP 注释或其他肯定不会导致测试失败的更改时，你可以提交并运行所有检查除了 PHPUnit，通过

DEV_LIB_SKIP=phpunit git commit

你可以通过逗号连接多个检查来跳过

DEV_LIB_SKIP=composer,phpunit,phpcs,yuicompressor,jscs,jshint,codeception,executebit git commit

自然地，你想要创建一个 Git 别名来使用你最常使用的命令，例如

git config --global alias.commit-without-phpunit '!DEV_LIB_SKIP="$DEV_LIB_SKIP,phpunit" git commit'

这样就可以执行以下操作（带有 Bash 自动完成）

git commit-without-phpunit

另外，你可以通过在提交消息中包含 [ci skip] 来跳过 Travis CI 构建。

运行特定检查

如果你想要运行一个特定的检查并忽略所有其他检查，你可以使用 DEV_LIB_ONLY 环境变量。例如，你可能想在提交之前只运行 PHPUnit。

DEV_LIB_ONLY=phpunit git commit

手动调用预提交

有时你可能想手动运行 pre-commit 检查来比较分支之间的更改（patches），就像 Travis CI 运行其检查一样。要比较当前暂存的更改与 master 的差异，执行

DIFF_BASE=master ./vendor/xwp/wp-dev-lib/scripts/pre-commit

要比较 master 和当前分支之间的提交更改

DIFF_BASE=master DIFF_HEAD=HEAD ./vendor/xwp/wp-dev-lib/scripts/pre-commit

限制检查范围

将自动化代码质量检查添加到现有项目的入门障碍可能在于，你的代码库可能存在大量在最初被报告的问题。因此，为了获得通过构建，你需要进行大量工作来清理代码库，使其符合 PHP_CodeSniffer、JSHint 等工具的要求。这不是理想的情况，并且可能在活动较多的项目中造成问题，因为这些更改将与其他人的拉取请求产生大量冲突。

为了解决这个问题，现在有一个用于配置的环境变量：CHECK_SCOPE。默认值是patches，这意味着当pre-commit运行或Travis在一个pull request或commit上运行构建时，检查将限制在它们的范围内，只报告发生变化的行（补丁）中的问题。检查补丁是最有用的，但可以在项目配置中添加CHECK_SCOPE=changed-files，以便检查限制在任何已修改文件的全部内容。

此外，需要注意的是，当pre-commit检查运行时，它将在暂存更改上运行linters（PHPCS，JSHint，JSCS等），而不是在工作树中存在的文件。这意味着您可以使用git add -p交互式选择要暂存的更改（这与git commit -a相比是一种良好的通用最佳实践），任何未暂存的代码都将被linters忽略。这在您有一些不打算提交的调试语句时非常有用（例如print_r()或console.log()）。

有了CHECK_SCOPE=patches和CHECK_SCOPE=changed-files，集成自动化检查现有项目就更容易了，这些项目可能有很多不合规的旧代码。您可以在修复错误和添加新功能的过程中逐步逐行或逐文件地修复代码库。

如果您想禁用范围限制行为，可以定义CHECK_SCOPE=all。

环境变量

您可以通过在仓库根目录中指定一个.dev-lib（以前是.ci-env.sh）Bash脚本来自定义.travis.yml和pre-commit钩子的行为，例如

DEFAULT_BASE_BRANCH=develop
PHPCS_GITHUB_SRC=xwp/PHP_CodeSniffer
PHPCS_GIT_TREE=phpcs-patch
PHPCS_IGNORE='tests/*,includes/vendor/*' # See also PATH_INCLUDES below
WPCS_GIT_TREE=develop
WPCS_STANDARD=WordPress-Extra
DISALLOW_EXECUTE_BIT=1
YUI_COMPRESSOR_CHECK=1
PATH_INCLUDES="docroot/wp-content/plugins/acme-* docroot/wp-content/themes/acme-*"
CHECK_SCOPE=patches

将DEFAULT_BASE_BRANCH设置为GitHub中的默认分支；这在Travis CI上构建分支的更改进行diff检查时使用。当dev-lib在网站上下文中使用时，PATH_INCLUDES特别有用，这样您就可以只针对您负责的主题和插件。对于排除，您可以指定一个PHPCS_IGNORE变量并覆盖.jshintignore；还有一个PATH_EXCLUDES_PATTERN。

PHPUnit代码覆盖率

为插件量身定制的phpunit.xml插件有一个filter，用于限制PHPUnit的代码覆盖率报告仅查看插件自己的PHP代码，省略WordPress核心和其他不应包含的地方的PHP。这个filter大大加快了PHPUnit的执行速度。要将代码覆盖率报告写入到code-coverage-report目录

phpunit --coverage-html code-coverage-report/

然后您可以在该目录中的index.html中打开它，了解您的插件代码覆盖率。

Codeception

通过以下方式启动Codeception：

wget -O /tmp/codecept.phar http://codeception.com/codecept.phar
php /tmp/codecept.phar bootstrap

然后更新接受性测试配置以反映您自己的环境设置

vim tests/acceptance.suite.yml

您可以通过以下方式生成第一个测试，保存到tests/acceptance/WelcomeCept.php：

php /tmp/codecept.phar generate:cept acceptance Welcome

Gitter

在您的仓库根目录中创建一个空的.gitter文件，并在您的项目的README中添加一个Gitter聊天徽章。

插件助手

该库包含一个WordPress README 解析器和转换器以 Markdown 格式，因此您无需手动保持WordPress.org上的 readme.txt 与GitHub上的 readme.md 同步。转换器还将自动识别具有Travis CI的项目，并将状态图像包含在markdown中。WordPress.org的截图和横幅图像也将自动集成到 readme.md 中。

此存储库还包括一个 svn-push，用于将GitHub存储库中的提交推送到WordPress.org插件SVN存储库。项目根目录中的 /assets/ 目录将自动移动到SVN存储库中一个目录之上（与 trunk、branches 和 tags 并排）。要使用，请在存储库根目录中包含一个 svn-url 文件，并让此文件包含到WordPress.org插件存储库的完整根URL（不要包含 trunk）。

贡献

请参阅贡献者文档。

致谢

查看所有贡献者。

此项目中的工具最初是为了方便开发 XWP 的插件而开发的。

xwp / wp-dev-lib

维护者

详情