开发工具#

XF2 为开发者提供了一系列内置工具，可以帮助加快插件的开发速度。下面我们将介绍其中一些工具。

调试模式#

调试模式可以在 config.php 中启用，启用后您可以在管理面板中访问某些开发工具（例如创建路由、权限、管理导航等），并且还会在每个页面的底部显示一个输出，详细说明页面处理所需的时间、执行了多少查询来渲染页面以及使用了多少内存。悬停时，会显示一个工具提示，包含有关当前控制器、操作和模板名称的信息。您还可以点击时间输出，这将为您提供详细的查询运行情况以及导致该查询执行的堆栈跟踪。

您可以通过在 config.php 中添加以下内容来启用调试模式：

src/config.php

$config['debug'] = true;

启用开发模式#

开发模式是一种特殊模式，在 config.php 文件中激活后，XF 会自动将开发文件写入您的 _output 目录。启用此模式后，才能启用文件系统模板编辑。由于开发模式会将文件写入文件系统，因此确保您具有适当的文件权限非常重要。这可能因环境而异，但典型的配置是确保您正在处理的任何插件的 _output 目录设置为 chmod 0777。例如，如果您正在处理一个 ID 为 Demo 的插件，其开发输出将写入 src/addons/Demo/_output，因此该目录需要完全可写。

启用开发模式后，调试模式也会自动启用。

要启用开发模式，请在 config.php 文件中添加以下行：

src/config.php

$config['development']['enabled'] = true;
$config['development']['defaultAddOn'] = 'SomeCompany/MyAddOn';

defaultAddOn 值是可选的，但添加该值后，在创建与插件关联的新内容时，XF 管理面板中会自动填充指定的插件。

除了上述内容外，您可能还需要添加一些额外的配置，特别是如果您使用多个 XF 安装。

src/config.php

$config['enableMail'] = false;

这将禁用从您的论坛发送的所有邮件。如果您使用的是带有真实用户和真实电子邮件地址的实时数据副本（尽管我们建议不要这样做！），这一点尤其重要。

作为直接禁用邮件的替代方案，您可能需要考虑使用诸如 MailTrap.io 之类的服务。这为您提供了一个免费的邮箱，可以接收从您的论坛发送的所有电子邮件，这对于测试新插件可能发送的任何电子邮件非常有用。

src/config.php

$config['cookie']['prefix'] = 'anything_';

如果您在同一域上使用两个或更多 XF 安装，可能会遇到 cookie 被覆盖的问题，这是由于安装共享相同的 cookie 前缀所致。因此，建议确保为您设置的每个 XF 安装更改 cookie 前缀。如果不这样做，您将遇到问题，例如在登录另一个 XF 安装时从一个 XF 安装中注销。

防止动态 IP 用户频繁注销#

XenForo 会话通常绑定到您的 IP 地址。如果您的 IP 地址是动态的，或者您使用 VPN、代理或负载均衡器，您可能会频繁注销。您可以通过在 src/config.php 文件中添加以下内容来防止这种情况：

src/config.php

$c->extend('session', function(\XF\Session\Session $session)
{
   $session->setConfig([
        'ipv4CidrMatch' => 0,
        'ipv6CidrMatch' => 0
    ]);
   return $session;
});

警告

您永远不应将上述代码应用于实时/生产站点的配置。

开发命令#

XF 2.0 附带了许多通用的开发和插件 CLI 命令，旨在帮助您更高效地开发，甚至可能自动化/脚本化一些常见流程。

在本节中，我们将介绍一些常用工具并解释它们的作用。

插件特定命令#

创建新插件#

终端

php cmd.php xf-addon:create

xf-addon:create 命令是初始设置和创建新插件的方式。运行后，您只需回答一些基本问题：

输入此插件的 ID
输入标题
输入版本 ID（例如 1000010）
输入版本字符串（例如 1.0.0 Alpha）

然后，您将获得创建插件并写出其 addon.json 文件的选项，并询问您是否要添加 Setup.php 文件。

导出 _data .XML 文件#

终端

php cmd.php xf-addon:export [addon_id]

此命令用于将插件的所有数据导出到 _data 目录中的 XML 文件。它从数据库中当前的数据导出（而不是从开发输出文件导出）。

提升插件版本#

终端

php cmd.php xf-addon:bump-version [addon_id] --version-id 1020370 --version-string 1.2.3

注意

如果您的版本字符串包含空格，则需要用引号括起来。

此命令接受插件的 ID、新版本 ID 和新版本字符串。这使您能够一步提升插件的版本，而无需自己执行升级和重建。上述选项是可选的，如果未提供，系统将提示您输入。如果仅指定版本 ID，我们将尝试根据推荐的版本 ID 格式自动推断正确的版本字符串。命令完成后，它会自动更新 addon.json 文件和数据库中的版本详细信息。

将 addon.json 同步到数据库#

终端

php cmd.php xf-addon:sync-json [addon_id]

有时您可能更喜欢直接编辑 JSON 文件以添加某些详细信息。这可能是版本、新图标或标题或描述的更改。以这种方式更改 JSON 可能会导致插件系统认为有待处理的更改或插件可升级。如果您尚未导出当前数据，则重建或升级可能是破坏性操作。因此，建议运行此命令作为导入数据的方式，而不会影响现有数据。

验证 addon.json 文件#

终端

php cmd.php xf-addon:validate-json [addon_id]

如果您想检查 JSON 文件是否包含正确的内容和格式，您现在可以验证它。验证器将检查内容是否可以解码，是否包含所有正确的必填字段（例如标题和版本 ID），并检查可选键（例如描述和图标）的存在。如果缺少任何键，系统将为您提供修复问题的选项。我们还会检查 JSON 文件中是否存在意外字段。这些可能是故意的或代表拼写错误。您可以手动运行该命令，或者在构建发布时自动运行该命令。

运行特定的安装步骤#

有时，检查您的安装类步骤是否正常运行很有用，而无需经历卸载和重新安装的过程。

有三个命令可以帮助解决这个问题。这些命令仅适用于使用默认 StepRunner 特性构建的安装类。

运行安装步骤#

终端

php cmd.php xf-addon:install-step [addon_id] [step]

运行升级步骤#

终端

php cmd.php xf-addon:upgrade-step [addon_id] [version] [step]

运行卸载步骤#

终端

php cmd.php xf-addon:uninstall-step [addon_id] [step]

构建插件发布#

完成所有艰苦的工作后，在真正发布之前还需要经历许多其他流程，这很遗憾。即使是将所有文件收集到正确的位置并手动创建 ZIP 文件的过程也可能耗时且容易出错。我们可以通过一个简单的命令自动处理这些问题，包括生成 hashes.json 文件。

终端

php cmd.php xf-addon:build-release [addon_id]

运行此命令时，它将首先运行 xf-addon:export 命令，然后将所有文件收集到一个临时的 _build 目录中，并将它们写入 ZIP 文件。完成的 ZIP 文件还将包含 hashes.json 文件。创建 ZIP 后，它将保存到您的 _releases 目录中，并命名为 <ADDON ID>-<VERSION STRING>.zip。

自定义构建过程#

除了创建发布 ZIP 文件外，您可能还希望在 ZIP 中包含其他文件，或者运行其他更高级的构建过程，例如压缩或连接 JS 或运行某些 shell 命令。所有这些都可以在您的 build.json 文件中处理。这是一个典型的 build.json 文件：

build.json

{
    "additional_files": [
        "js/demo/portal"
    ],
    "minify": [
        "js/demo/portal/a.js",
        "js/demo/portal/b.js"
    ],
    "rollup": {
        "js/demo/portal/ab-rollup.js": [
            "js/demo/portal/a.min.js",
            "js/demo/portal/b.min.js"
        ]
    },
    "exec": [
        "echo '{title} version {version_string} ({version_id}) has been built successfully!' > 'src/addons/Demo/Portal/_build/built.txt'"
    ]
}

如果您有需要在插件目录之外提供的资源（例如 JavaScript），您可以使用 build.json 中的 additional_files 数组告诉构建过程复制文件或目录。在开发过程中，并不总是可以将文件保留在插件目录之外，因此如果您愿意，可以将文件保留在插件的 _files 目录中。复制附加文件时，我们将首先检查该目录。

如果您随插件提供了一些 JS 文件，您可能希望出于性能原因压缩这些文件。您可以在 build.json 中指定要压缩的文件。您可以将这些文件列为数组，或者只需指定为 '*'，这将压缩 js 目录中的所有文件，只要在复制附加文件到构建后该路径中包含 JS 文件。任何压缩的文件将自动具有 .min.js 后缀，而不是 .js，原始文件仍将包含在包中。

您可能更喜欢将多个 JS 文件合并为一个文件。如果是这样，您可以使用 rollup 数组来定义。键是生成的组合文件名，数组中的项目是将组合到单个文件中的 JS 文件的路径。

最后，您可能有一些需要在包构建和完成之前运行的特定过程。这可能是任何组合。最终，如果它是可以从 shell 运行的命令（包括 PHP 脚本），则可以在此处指定。上面的示例当然相当无用，但它确实至少演示了可以使用某些占位符。这些占位符将替换为可以从 XF\AddOn\AddOn 对象获取的标量值，通常是 addon.json 文件中可用的任何值，或 AddOn 实体。

开发命令#

实际上有很多与开发相关的命令，但这里仅介绍最重要的两个。

要使用这些命令中的任何一个，您必须在 config.php 文件中启用开发模式。

警告

如果数据库和 _output 目录不同步，以下两个命令都可能导致数据丢失。始终建议使用 VCS（版本控制系统），例如 GitHub 来减轻此类错误的影响。

导入开发输出#

终端

php cmd.php xf-dev:import --addon [addon_id]

运行此命令将从插件 _output 目录导入所有开发输出文件到数据库中。

导出开发输出#

终端

php cmd.php xf-dev:export --addon [addon_id]

这将导出数据库中当前与插件关联的所有数据到 _output 目录中的文件。

调试代码#

应该可以设置您最喜欢的调试器工具（XDebug、Zend Debugger 等）以与 XF2 一起使用。不过，有时调试代码可能就像快速查看变量在给定时间持有的值（或值类型）一样简单。

转储变量#

PHP 当然有一个内置工具来处理这个问题。您可能知道它是 var_dump()。XF 附带了两个替代方案：

PHP

\XF::dump($var);
\XF::dumpSimple($var);

简单版本主要只是以纯文本形式转储变量的值。例如，如果您仅使用它来转储数组的值，您将在页面顶部看到如下输出：

转储

array(2) {
  ["user_id"] => int(1)
  ["username"] => string(5) "Admin"
}

这实际上与标准 var_dump 的输出相同，但经过稍微修改以提高可读性，并包装在 <pre> 标签内以确保渲染时保留空白。

替代方案实际上是 Symfony 项目中的一个名为 VarDumper 的组件。它输出 HTML、CSS 和 JS 以创建更具功能性和可能更易读的输出。它允许您折叠某些部分，并且对于某些可以输出大量数据的值（例如对象），它可以自动折叠这些部分。