1.phpBB Extensions Getting Started

介绍

欢迎来到phpBB的扩展开发教程和文档。

这些教程页面是基于phpBB的Acme Demo(https://github.com/phpbb/phpbb-ext-acme-demo)扩展，这个简单的扩展展示了关于一个扩展的许多共同特性，包括使用一个前台页面、通过核心事件和模板事件修改phpBB、使用迁移来修改数据库，为修改配置设置一个ACP模块。

这篇教程包括了扩展的基本创建：

扩展文件夹

Composer JSON

phpBB Skeleton 扩展是一个帮助开发人员快速生成phpBB新扩展所需的初始文件组件

扩展文件夹

所有的扩展必须位于phpBB根目录下的ext/文件夹

扩展程序使用文件夹结构打包，如下所示：vendor/extname。

因此，扩展应该位于phpBB目录中，如下所示：phpBB/ext/vendor/extname。

vendor名字可能是作者的用户名或者其他任何你选择组织你的扩展的名字。extensio名字是扩展的名字。在这个教程中我们将使用 acme 作为 vendor的名字 ，demo作为扩展的名字。

vendor和extension的名字必须以小写或者大写字母开头，后跟字母和数字。不允许下划线，破折号和其他字符。有一个扩展名为iamanextension是完美的。

Composer JSON

每一个扩展都需要一个名为composer.json的元数据文件，以便phpBB识别您的扩展。此文件包含有关扩展及其依赖关系的基本信息。它必须用用json格式写成并且存储在扩展根文件夹下面，例如：phpBB/ext/acme/demo/composer.json。

composer.json中的信息将由ACP中的扩展管理器使用。元数据的细节将在下面的示例中进行说明，但现在我们来看看完整的文件：

最重要的是记住，任何JSON数组中的最后一个项目或对象不能包含一个逗号。

name 非空 vendor名字和扩展名字，以/分隔，匹配文件夹结构

type 非空 包的类型。应该始终为phpbb-extension。

description 非空 一个简短的介绍扩展的描述，可能为空，但是不能跳过。

homepage 可以为空 一个有效的URL。建议使用定制数据库中的贡献链接或扩展名的存储库（如果您使用像GitHub这样的公共文件）。

version 非空 你的扩展的版本号。这应该遵循X.Y.Z的格式，后缀为-dev， -patch，-alpha，-beta或-RC。

time 可以为空 你的扩展的发布日期。必须是YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS 格式。

keywords 可以为空 一个和扩展有关的关键字数组

license 非空 包的证书。这可以是字符串或字符串数组。通常扩展应该按照与phpBB相同的GPL-2.0许可证授权。

authors 非空 一个数组，其值为扩展的作者名。更多细节请看作者。

require 非空 一个扩展需求的数组。更多细节请看require

require-dev 可以为空 一系列扩展的开发要求。更多细节请看require-dev。

extra 非空 一组任意额外的数据。查看extra的更多细节。

authors

你可能有无限的作者。至少有一位作者强烈推荐。

name 非空 作者名字

email 可以为空 作者的email

homepage 可以为空 一个指向作者网站的URL。

role 可以为空 角色可用于指定作者对扩展程序的作用（例如开发人员，翻译者，支持者等）

require

列出扩展所需的依赖关系，即PHP版本和第三方库。

php 扩展所需的PHP的最小稳定版本。phpBB 3.2需要PHP 5.4.0或更高版本，所以版本需要 >= 5.4.0。

composer/installers 由phpBB推荐 这将通过Composer安装在phpBB中的正确位置的扩展名。

require-dev

在可选的require-dev部分中，您可以列出只需要开发的扩展的依赖关系。Acme Demo使用来自phpBB Extensions Team的扩展预验证工具在Travis CI上运行测试时执行一些基本验证（请参阅教程：测试）。由于我们总是想拥有最新版本，所以我们需要dev-master

extra

根据composer的规范，这一部分可以包含几乎任意数据。但是，phpBB需要在这个数组中有两个特殊条目用于扩展：

display-name 扩展的名字，例如：Acmo Demo Extension.

soft-require 这个扩展所需的phpBB最小稳定版本。在这种情况下，我们需要任何3.1版本，它通过将其前缀到～：“phpbb/phpbb”:"~3.2"来完成。

有关composer.json文件中可用的所有json模式字段的完整说明，请参见：https://getcomposer.org/doc/04-schema.md

有关指定包版本约束的更多信息，请参见：https://getcomposer.org/doc/articles/versions.md#basic-constraints

到目前为止，我们的扩展还没有功能。继续阅读下一部分，了解如何编写一个有用的扩展名。