开发工具¶

XF2 为开发者提供了大量的内置工具，您可以使用这些工具来加快附加组件的开发，下面我们将介绍其中的一些。

调试模式¶

调试模式可以在你的 config.php 中激活，这将允许你访问 Admin CP 中的某些开发工具（如创建路由，权限，管理导览等），它还将在每个页面的底部激活一个控制台输出，详细说明页面处理的时间，有多少查找被运行来喧染页面和使用了多少内存。 悬停时，会有一个包含当前 Controller、 Action 和模板名称等信息的工具提示。 你也可以点击时间输出，这将让你详细了解到底运行了哪些查找，以及导致该查找被运行的堆栈追踪。

你可以通过在 config.php 中添加以下内容来激活调试模式：

$config['debug'] = true;

激活开发模式¶

开发模式是一种特殊的模式，在您的 config.php 文件中激活，它将触发 XF 自动将您的开发文件写入 _output 目录。 这个模式需要在文件系统模板编辑时激活。 由于开发模式会将文件写入你的文件系统，确保你有适当的文件权限是很重要的。 这可能会根据环境的不同而有所不同，但典型的配置是确保你正在使用的任何附加组件的 _output 目录的 chmod 设置为0777。 例如，如果你正在使用一个 ID 为 Demo 的附加组件，它的开发输出将被写入到 src/addons/Demo/_output，因此该目录需要是完全可写的。

激活开发模式，也会自动激活 调试模式。

要激活开发模式，请在你的 config.php 文件中添加以下行：

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

defaultAddOn 值是可选的，但当创建新内容时，添加该值会在 XF Admin CP 中自动填充指定的附加组件，该附加组件将与附加组件相关联。

除了上述，你可能会发现有必要添加一些额外的配置，特别是当你使用多个 XF 安装时。

$config['enableMail'] = false;

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

除了直接关闭邮件之外, 您可以考虑使用一个服务, 例如 MailTrap.io。 这将为您提供一个免费的邮箱，可以接収所有从您的论坛发送的邮件，这对于测试您的新附加组件可能发送的任何电子邮件非常有用。

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

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

开发命令¶

XF 2.0 提供了一些通用的开发和附加组件的 CLI 命令，这些命令的目的是帮助您更有效地开发，甚至可能使一些常见的过程自动化/脚本化。

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

附加组件特定命令¶

新建一个附加组件¶

xf-addon:create 命令是如何初始设置和创建一个新的附加组件。 一旦它运行，你只需要回答一些基本问题：

• 输入此附加组件的 ID
• 输入标题
• 输入版本 ID（如 1000010 ）。
• 输入版本字符串（如 1.0.0 Alpha）。

然后你会得到一个选项来创建附加组件并写出它的 addon.json 文件，并询问你一些关于是否要添加 Setup.php 文件的问题。

导出 _data .XML 文件¶

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

升级您的附加组件版本¶

该命令获取您的附加组件的附加组件 ID、新版本 ID 和新版本字符串。 这样您就可以轻松完成升级附加组件的版本，而无需自己运行升级和重建。 上面的选项是可选的，如果没有提供这些选项，系统会提示您输入。 如果您只指定版本 ID，如果它符合我们推荐的版本ID格式，我们将尝试并自动从中推断出正确的版本字符串。 一旦命令完成，它将自动更新 addon.json 文件和数据库，并提供正确的版本详细信息。

同步你的 addon.json 到数据库¶

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

验证您的 addon.json 文件¶

如果你想检查你的 JSON 文件是否包含正确的内容和正确的格式，你现在可以验证它。 验证器将检查内容是否可以解码，是否包含所有正确的必填字段（如标题和版本 ID ），还检查是否存在可选的 Key（如描述和图标）。 如果有任何 Key 丢失，我们将为您提供修复问题的服务。 我们还检查 JSON 文件中是否有任何意外的字段。 这些可能是故意的，也可能是错别字。 您可以手动运行该命令，或者在构建发行版时自动运行该命令。

运行特定的设置步骤¶

有时，无需进行卸载和重新安装过程即可检查 Setup class 步骤是否正常运行，这是很有帮助的。

有三条命令可以帮助解决这个问题，这些命令只适用于使用默认的 StepRunner 特性创建的 Setup class。

运行安装步骤¶

运行升级步骤¶

运行卸载步骤¶

构建附加组件发行版¶

一旦所有的艰苦工作都完成了，很遗撼，在真正发布之前还要经历一些其他的过程。 即使是将所有的文件収集到正确的地方，并手动创建 ZIP 文件的过程也是很耗时的，而且容易出现错误。 我们可以自动处理这些问题，包括用一个简単的命令生成 hash.json 文件。

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

自定义构建过程¶

除了创建发布的 ZIP 之外，您可能还希望在 ZIP 中包含其他的文件，您希望运行其他更高级的构建过程，如最小化或连接 JS 或运行某些 shell 命令。 所有这些都可以在你的 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'"
    ]
}

如果你有一些需要在 add-on 目录之外提供服务的 assets，比如 JavaScript，你可以使用 build.json 中的 additional_files 数组告诉构建过程复制文件或目录。 在开发过程中，将文件保存在 add-on 目录之外并不总是可行的，所以如果你愿意，你可以将文件保存在 add-on 的 _files 目录中。 在复制附加文件时，我们将首先检查该文件。

如果您的附加组件附带了一些 JS 文件，出于性能考虑，您可能会希望对这些文件进行最小化。 您可以在您的 build.json 中指定您要最小化的文件。 您可以将这些文件以数组的形式列出，也可以直接指定为 '*'，这样就会对 js 目录中的所有文件进行最小化，只要该路径中存在 JS 文件，并将额外的文件复制到构建中即可。 任何被最小化的文件都会自动以 .min.js 作为后缀，而不是 .js ，并且源文件案仍然在包中。

你可能更喜欢将多个 JS 文件捆成一个文件。 如果你这样做，你可以使用 rollup 数组来定义。 key 是合并后的文件名，数组中的 item 是 JS 文件的路径，这些文件将被合并成一个文件。

最后，您可能需要在打包构建和最终定案之前运行某些进程。 这可能是任何东西的组合。 归根结底，如果它是一个可以从 shell 中运行的命令（包括 PHP 脚本），那麽你可以在这里指定它。 当然，上面的示例是毫无用处的，但它至少证明了某些保留区是可以使用的。 这些保留区被替换为标量值，你可以从 XF\AddOn\AddOn 物件中获得，一般来说，这个物件是 addon.json 文件中的任何可用值，或者 AddOn 实体。

开发命令¶

其实与开发相关的命令有不少，但这里只介绍最重要的两个。

要使用这些命令，你必须在你的 config.php 文件中激活开发模式。

导入开发输出¶

运行此命令将把你的附加组件 _output 目录下的所有开发时输出的文件导入进数据库里。

导出开发输出¶

这将把当前数据库中与附加组件相关联的所有数据导出到 _output 目录下的文件中。

调试代码¶

应该可以设置你喜欢的调试工具（ XDebug，Zend Debugger 等）来与 XF2 一起运作。 虽然，有时候，调试代码可能象快速查看一个变量在给定时间内持有的值（或值类型）一样简陋。

Dump 变量¶

当然 PHP 有一个内置的工具来处理这个问题，您可能将其称为 var_dump()。 XF 提供了两个替代方法来处理这个问题：

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

简単版本主要是将一个变量的值以纯文本的形式転储出来。 例如，如果你只是用它来転储一个数组的值，你会在页面顶部看到这样的输出：

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

这实际上是与标准的 var_dump 相同的输出，但为了可读性稍作修改，并将其包裹在 <pre> 标签中，以确保在喧染时保留空白。

这个替代方案实际上是 Symfony 项目中的一个名为 VarDumper 的组件。 它输出 HTML、 CSS 和 JS 来创建一个功能更强、更容易阅读的输出。 它允许你折叠某些部分，对于某些可以输出大量数据的值，比如物件，它可以自动折叠这些部分。