2.phpBB Extensions Key Concepts

行业资讯

admin

发布时间：2024-03-19

浏览：49 次

介绍

在我们可以让我们的扩展做好事情之前，我们需要介绍phpBB中使用的一些关键概念和实践。

本教程解释：

Dependency injection

PHP files

Template files

Language files

Javascript and CSS files

Dependency injection 依赖注入

自3.1以来，phpBB代码库的大部分基于一个基本机制，即依赖注入。目标是不必担心管理要使用的组件（例如数据库层，缓存系统或当前用户对象）的不同依赖关系。这也是停止使用全局变量的方法。

由于phpBB3.1是使用Symfony DependencyInjection组件实现的。phpBB提供的所有服务都是在/config/services.yml中的YMAL格式文件中定义的。扩展可以使用由phpBB定义的服务，也可以在自己的config/services.yml中为自己的PHP类定义自己的服务。

为了提供一个简单的依赖注入示例，我们来看看Acme Demo的控制器类main.php的构造方法：

public function __construct(\phpbb\config\config $config, \phpbb\controller\helper $helper, \phpbb\template\template $template, \phpbb\user $user)

{

$this->config = $config;

$this->helper = $helper;

$this->template = $template;

$this->user = $user;

}

您可以看到，它需要$config，$helper，$template和$user对象（a.k.a. services）。要通过依赖注入自动解决这些服务，Acme Demo扩展必须在其config / services.yml中将其控制器类定义为服务：

services:

acme.demo.controller:

class: acme\demo\controller\main

arguments:

- @config

- @controller.helper

- @template

- @user

请注意，acme.demo.controller是该类的唯一服务名称。扩展名必须以供应商和扩展名（在这个例子中为acme.demo）为前缀，以防止与其他扩展或核心服务的潜在冲突。

该类只是类的名称间隔路径。

参数是类所需的服务依赖关系。参数的顺序必须与__construct（）方法定义中的参数顺序一致很重要。任何以@或％符号开始的参数都应该用单引号括起来（这将是从phpBB 3.2开始的）。

扩展中的大多数PHP文件应该使用具有服务定义的依赖注入模型，特别是控制器和事件监听器。例外情况是ACP / MCP / UCP文件，语言文件和迁移文件（目前不使用服务容器）。

也可以看看

依赖注入容器维基 https://wiki.phpbb.com/Dependency_Injection_Container

Symfony：依赖注入组件 http://symfony.com/doc/2.3/components/dependency_injection/introduction.html

PHP文件

作为phpBB向广泛使用面向对象转变的一部分，开发人员可以使用类来适当地组织数据。鼓励扩展用于将相关功能存储在类中，并在其自己的文件中存储类。

类的命名对于一致性很重要。所有类应该是名称间隔的，并且具有到路径名映射的直接类; 换句话说，名称和类名必须包含目录结构。例如：

<?php namespace acme\demo\controller; class main { // do something }

上述名称间隔的代码将是一个类文件和路径结构，如acme/demo/controller/main.php。

适当的名称间隔类由phpBB自动加载，这意味着访问器函数不需要为其他类访问。

注意

phpBB 3.1编码指南指出，PHP文件中不需要关闭？>，所有文件最后都应包含一个额外的空白行。

IN_PHPBB 安全

仅类的PHP文件不需要使用IN_PHPBB安全测试。但是，如果您的PHP文件包含未封装在类结构中的任何可执行代码，例如暴露的函数，define（），include（）或require（）语句或其他工件，则在执行任何可执行代码之前需要IN_PHPBB测试：

<?php if (!defined(IN_PHPBB)) { exit; } include(somefile.php); function do_something () { // do something }

也可以看看

phpBB 3.1编码指南。https://area51.phpbb.com/docs/31x/coding-guidelines.html

phpBB自定义数据库PHP验证策略。https://www.phpbb.com/extensions/rules-and-policies/validation-policy/#php

模板文件

一般来说，扩展的模板与phpBB3的模板没有区别。 phpBB 3.1已经切换到Twig模板引擎，但是保留了phpBB的原始模板语法。因此，扩展中允许使用phpBB或Twig模板语法。如果您不熟悉Twig，您可以使用phpBB的语法。

扩展名可以包含两种类型的模板文件：自定义模板和模板事件和监听器。扩展程序的自定义模板文件应具有唯一的名称，最好以供应商和扩展名为前缀，以防止与其他扩展或phpBB模板文件发生冲突。除了模板文件，扩展可以包含主题文件（CSS脚本和图像），Javascript文件和其他资源。

扩展中的模板文件应该以类似于phpBB的模板文件结构的方式进行组织。 styles /目录应包含您为每个样式编写的模板文件的目录。例如，prosilver和subsilver2。从prosilver继承的任何风格，都将继承自您的扩展程序的pros目录。

特殊的全部/目录可以用于包含可以与任何和所有样式一起使用的模板文件（例如通用的JS文件）。

ACP的模板文件应该存储在adm / style / location中，类似于phpBB的结构。

具有通用（全）文件和主题特定文件的扩展的示例目录结构：

styles

├── all

│ ├── template

│ │ └── event

│ │ └── overall_header_head_append.html

│ └── theme

│ ├── css

│ │ └── acme_demo_main.css

│ └── images

│ └── acme_demo_image.png

├── prosilver

│ └── template

│ ├── acme_demo_body.html

│ └── event

│ └── overall_header_navigation_append.html

└── subsilver2

└── template

├── acme_demo_body.html

└── event

└── overall_header_navigation_append.html

警告

如果标准phpBB模板文件名用于扩展模板，那么它将覆盖来自phpBB的模板文件。因此，在命名模板文件时要注意这一点。覆盖模板文件不适用于公开发布的扩展，因为它可能与其他扩展冲突。

语言文件

扩展程序中的语言文件应以类似于phpBB的语言文件结构的方式进行组织。语言/目录应该包含每个翻译语言的目录。请注意，所有扩展都需要en英文，因为它是phpBB中的默认语言。

Acme演示扩展程序的语言文件如下所示：

<?php if (!defined(IN_PHPBB)) { exit; } if (empty($lang) || !is_array($lang)) { $lang = array(); } $lang = array_merge($lang, array( DEMO_PAGE => Demo, DEMO_HELLO => Hello %s!, DEMO_GOODBYE => Goodbye %s!, ACP_DEMO_TITLE => Demo Module, ACP_DEMO => Settings, ACP_DEMO_GOODBYE => Should say goodbye?, ACP_DEMO_SETTING_SAVED => Settings have been saved successfully!, ));

使用$ language对象的add_lang（）方法，在扩展名中加载语言文件是足够简单的。它有两个参数，第一个是语言文件的名称（或一组语言文件名），第二个是扩展供应商/包。

注意

该语言对象在3.2中引入，提供从User对象中提取的专门的语言方法类。以前在User对象中使用add_lang_ext（）的方法已经在3.2中弃用了，最终将在将来被删除。

// Load a single language file from acme/demo/language/en/common.php $language->add_lang(‘common’, ‘acme/demo’); // Load multiple language files from // acme/demo/language/en/common.php // acme/demo/language/en/controller.php $language->add_lang(array(‘common’, ‘controller’), ‘acme/demo’);

出于性能原因，最好使用上述方法在需要语言键的扩展代码执行中的任何位置加载语言文件。但是，如果绝对需要在全局加载扩展的语言键，所以它们始终可用，应该使用core.user_setup PHP事件。

javascript和css文件

javascript和css文件可以存储在你的扩展的任何地方。但是，最常见的位置在您的样式文件夹中。使用phpBB的 和 模板语法可以方便地将这些脚本添加到扩展模板中。

这些INCLUDE标签的格式采用以下形式：

INCLUDECSS标签将根据用户的当前样式或所有样式文件夹（如果存在）查找扩展名的风格主题文件夹中的命名文件。 INCLUDECSS标签将在HTML文档的<head>部分自动生成提供的CSS文件<link>标签。

INCLUDEJS标签将根据用户当前的样式或所有样式文件夹（如果存在）查找扩展名的样式模板文件夹中的命名文件。 INCLUDEJS标签将在HTML文档的页脚中自动生成提供的JS文件<script>标签。

注意

INCLUDECSS标签只能在overall_header_head_append模板事件中工作。但是，INCLUDEJS标记可以在任何模板事件或自定义模板文件中使用。

当包含JavaScript / CSS库和框架（如jQuery-UI或Font Awesome）时，可以使用由phpBB扩展团队批准的简单解决方案来减轻扩展之间资源重叠的潜力。使用<！ - DEFINE - >标签，您应该测试您的扩展程序想要包含的脚本是否已经定义，如果不是，则包含脚本并定义脚本。例如：

一些使用公共库的示例模板变量定义（通常的做法应该是在库文件名之后命名变量定义，例如，highslide.js变为HIGHSLIDEJS）：

HighSlide JS: $INCLUDED_HIGHSLIDEJSFont Awesome CSS: $INCLUDED_FONTAWESOMECSSColorBox JS: $INCLUDED_COLORBOXJSColPick JS: $INCLUDED_COLPICKJSMoTools JS: $INCLUDED_MOTOOLSJSDojo JS: $INCLUDED_DOJOJSAngular JS: $INCLUDED_ANGULARJS

也可以看看

phpBB自定义数据库JavaScript和CSS验证策略。

现在我们已经介绍了phpBB中PHP，模板，语言和资源文件的工作原理，我们已经准备好继续下一节了解如何将扩展扩展到功能上。