Что такое расширение в phpBB 3.1 / Ascraeus ?

В данном подфоруме будут располагаться все статьи, помогающие освоиться в администрировании форума phpBB 3.1 / Ascraeus.

Модераторы: Vl@d1m1r, Lorem Ipsum, Atlas

Ответить
Аватара пользователя
DeaDRoMeO
Старожил Форума
Старожил Форума
Сообщения: 16763
Стаж: 13 лет
Откуда: Витебск
Контактная информация:

Что такое расширение в phpBB 3.1 / Ascraeus ?

Сообщение DeaDRoMeO »

С выходом первых дорелизных версий phpBB 3.1 в нашем лексиконе вместо слово Модификация появилось слово Расширение. Появилось оно не просто так, а потому что в phpBB 3.1 код форума не редактируется при установке различных дополнений, а расширяется посредством так называемых расширений. Итак, все же что такое расширение ?

Расширение - это новая система изменения и дополнения функционала phpBB, представленная в версии phpBB 3.1, пришедшая на смену модам, использовавшимся в версии phpBB 3.0. Представляет из себя набор файлов, копируемых в папку /ext. Включение и настройка расширения осуществляется через администраторский раздел.
Основное преимущество системы расширений - отсутствие необходимости вручную вносить изменения в исходный код и базу данных phpBB. Первое основано на так называемых Событиях.

Событие (event) - это строка (как правило, одна или две) в исходном коде, добавленная разработчиками. События подразделяются на два вида: событие ядра и событие шаблона. Каждое событие имеет собственный идентификатор, по которому определяется, код каких расширений и в каком месте будет выполняться.
Пример: событие ядра в posting.php

Код: Выделить всё

$vars = array('post_id', 'topic_id', 'forum_id', 'draft_id', 'lastclick', 'submit', 'preview', 'save', 'load', 'delete', 'cancel', 'refresh', 'mode', 'error');
extract($phpbb_dispatcher->trigger_event('core.modify_posting_parameters', compact($vars)));
В данном случае, идентификатором события является имя core.modify_posting_parameters. Массив $vars содержит список переменных, которые будут переданы расширению и могут быть им использованы, в том числе изменены/дополнены их значения.

Пример: событие шаблона в quickreply_editor.html

Код: Выделить всё

<!-- EVENT quickreply_editor_message_before -->
В данном случае идентификатором события является имя quickreply_editor_message_before.

В свою очередь, в расширениях имеются так называемые "слушатели" (или подписчики) событий ядра (listeners, event subscribers), представляющая собой сопоставление идентификатора события с именем функции в расширении, которая должна быть вызвана при возникновении данного события.
Например:

Код: Выделить всё

static public function getSubscribedEvents()
	{
		return array(
			'core.page_header'					=>	'show_quicknick',
			'core.viewtopic_modify_page_title'	=>	'show_bbcodes_and_smilies',
			'core.modify_posting_parameters'	=>	'change_subject',
			'core.posting_modify_template_vars'	=>	'delete_re',
		);
	}

Существуют еще События шаблонов, для них система обработки немного отличается. При возникновении такого события, система пытается найти html файл, названный по имени данного события, в подпапках расширения, связанных со стилями. Например, для события <!-- EVENT quickreply_editor_message_before --> будет предпринята попытка найти файл quickreply_editor_message_before.html в папках /ext/test/quickreply/styles/prosilver/template/event/, /ext/test/quickreply/styles/subsilver2/template/event/ и аналогичных для других стилей, либо /ext/test/quickreply/styles/all_styles/template/event/, если данный шаблон события будет общим для всех стилей.

Какова файловая структура расширений ?

Расширения должны иметь определенную структуру - т.е. минимально необходимый набор папок и файлов, определяющих его работу:

Код: Выделить всё

\config\
\event\
\migrations\
\composer.json
\ext.php
Остановимся на некоторых из них

1) Папка config.
В ней расположен единственный файл - services.yml, который передает системе основные сведения о расширении, его расположении и используемых им так называемых "сервисах" - т.е. встроенных классах и переменных phpBB. Например:

Код: Выделить всё

services:
    test.quickreply.listener:
        class: test\quickreply\event\listener
        arguments:
            - @auth
            - @config
            - @dbal.conn
            - @template
            - @user
            - %core.root_path%
            - %core.php_ext%
        tags:
            - { name: event.listener }
Оператор services является стандартным и не подлежит изменению.

Строка test.quickreply.listener: задает основной сервис расширения - имя класса слушателя события listener для расширения, находящегося в папке /ext/test/quickreply.

Строка class: test\quickreply\event\listener задает имя файла, в котором располагается класс. В данном случае это файл ext/test/quickreply/event/listener.php.

Блок arguments: задает перечень аргументов, которые будут использованы в конструкторе класса. Аргументы в конструкторе должны следовать исключительно в том же порядке, в котором они указаны здесь.
В данном случае мы видим, что конструктор расширения будет использовать стандартные классы phpBB: auth, config, db, template, user, а также переменные phpbb_root_path и php_ext. А вот как это выглядит на практике:

Код: Выделить всё

public function __construct(\phpbb\auth\auth $auth, \phpbb\config\config $config, \phpbb\db\driver\driver $db, \phpbb\template\template $template, \phpbb\user $user, $phpbb_root_path, $php_ext)
	{
		$this->auth = $auth;
		$this->config = $config;
		$this->db = $db;
		$this->template = $template;
		$this->user = $user;
		$this->phpbb_root_path = $phpbb_root_path;
		$this->php_ext = $php_ext;
	}
Аргументы следуют в том порядке, в котором они указаны в файле services.yml.

2) Папка event.
Папка срдержит файл, содержащий слушатели событий ядра. Если говорить проще - тут находится весь рабочий PHP код расширения. Следуя логике этой статьи, файл должен называться /event/listener.php.
Внутри файла находится основной класс расширения, фактически отвечающий за весь его функционал, являющийся потомком встроенного класса EventSubscriberInterface:
class listener implements EventSubscriberInterface
.

Первой и второй стандартными функциями, с которыми мы встречаемся в данном классе, являются уже упомянутые выше конструктор класса public function __construct()и список событий, на которые подписано расширение static public function getSubscribedEvents().
Все остальные функции являются пользовательскими, их имена, структура и исполняемый код зависят непосредственно от той задачи, которую решает расширение.

3) Папка migrations.
Здесь находятся файлы с инструкциями, ответственными за внесение дополнений и изменений в базу данных (добавление новых таблиц, столбцов в имеющихся таблицах, изменение и добавление новых конфигурационных параметров в таблицу _config, и так далее).
Как правило, файл именуется в соответствии с версией расширения, например, v_0_0_1.php.
Внутри файла находится класс, являющийся потомком класса \phpbb\db\migration\migration, имя которому присваивается также исходя из версии расширения, например:v_0_0_1.
Таким образом, получаем определение класса: class v_0_0_1 extends \phpbb\db\migration\migration.

Класс миграции состоит из набора стандартных функций, но могут быть и нестандартные.

Стандартными функциями являются:

public function effectively_installed() - отвечает за проверку версии расширения;
static public function depends_on() - отвечает за определение встроенного класса миграции, необходимого для внесения изменений в БД;
public function update_schema() - отвечает за внесение изменений в схему БД;
public function revert_schema() - отвечает за возврат схемы БД в начальное состояние при удалении расширения;
public function update_data() - отвечает за внесение новых данных в БД (в том числе конфигурационных данных, добавление новых модулей в администраторский/модераторский/личный разделы, добавление новых прав доступа и пр.);
public function revert_data() - отвечает за восстановление данных в исходном виде при удалении расширения.


4) Файл composer.json.
Данный файл отвечает за предоставление системе основной информации о расширении - его названии, версии, лицензии, авторе (или группе авторов), системных требованиях. К примеру

Код: Выделить всё

{
	"name": "phpbbworld/snow",
	"type": "phpbb-extension",
	"description": "Расширение добавляет снегопад на ваш форум",
	"homepage": "http://phpbbworld.ru/viewtopic.php?f=6&t=14",
	"version": "0.1.0",
	"time": "2014-06-28",
	"license": "GPL-2.0",
	"authors": [{
			"name": "DeaDRoMeO",
			"username": "Sergey",
			"email": "barkovskiis@yandex.ru",
			"homepage": "http://phpbbworld.ru",
			"role": "Administrator"
		}],
	"require": {
		"php": ">=5.3.3"
	},
	"extra": {
      "display-name": "Снегопад",
      "soft-require": {
         "phpbb/phpbb": "3.1.*@dev"
      }
   }
}
5) Файл ext.php.
ext.php считается основным файлом расширения, но вместе с этим это служебный файл, не содержащий полезной информации, его пример

Код: Выделить всё

<?php
/**
*
* @package thanks_for_posts
* @copyright (c) 2014 gfksx
* @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2
*
*/

namespace gfksx\thanks_for_posts;

/**
* Main extension class for this extension.
*/
class ext extends \phpbb\extension\base
{
}
Так же помимо вышеописанных файлов и папок в папке расширения могут присутствовать и другие каталоги, к примеру языковые папки....

Пффф, расширения это не такая уж и простая вещь :hi_hi_hi:
На вопросы, связанные с phpBB, по ЛС не отвечаю !!!
#1
Ответить
  • Похожие темы
    Ответы
    Просмотры
    Последнее сообщение