1 Topic by PunBB (edited by PunBB 2017.07.15 08:48)

Topic: Как написать свое расширение для форума PunBB

Наверное не раз возникал такой вопрос и у вас. На самом деле написать свое расширение для форума PunBB не так уж и сложно, нужно немного знать php и систему по которой работают расширения и хуки. Но не будем философствовать, а перейдем сразу к делу. Давайте вместе создадим простое расширение. Например, напишем расширение позволяющее при переходе по ссылке Поиск, открывать расширенный поиск.

Как правильно назвать расширение

Когда вы создали новую директорию, ей нужно присвоить уникальный идентификатор (ID).
В имени идентификатора можно использовать латинские буквы, цифры и символ подчеркивания (_).
Лучше использовать свой префикс вначале имени как это есть у официальных расширений pun_ Например my_. Тогда не будет конфликтов из за совпадений ID.
В нашем случае  присвоим ID pan_search_advanced.

Итак, мы создали папку с именем pan_search_advanced.

2 Reply by PunBB (edited by PunBB 2016.10.20 15:37)

Re: Как написать свое расширение для форума PunBB

Какие файлы должно содержать расширение

Первым делом создайте в корне папки нашего нового расширения пустой файл с именем index.html. Таким образов вы запретите просмотр содержимого директорий и файлов злоумышленниками. Каждый раз создавая директорию - создавайте пустой файл index.html, это важно для безопасности вашего форума.

Следующим важным файлом является manifest.xml. Вот его стандартная структура:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE extension SYSTEM "ext-1.0.dtd">

<extension engine="1.0">
  <id>pan_search_advanced</id>
  <title>Pan Search Advanced</title>
  <version>0.1</version>
  <description>Расширенный поиск для форума PunBB</description>
  <author>PunBB</author>
  
  <minversion>1.4.2</minversion>
  <maxtestedon>1.4.4</maxtestedon>
  
  <dependencies>
    <dependency>pun_jquery</dependency>
  </dependencies>
  
  <note type="install" timing="pre">
    Внимание! Это предупреждающее сообщение перед установкой.
  </note>
  
  <install><![CDATA[ 
//Код для установки (не обязательно)
//Создание таблиц в БД, полей и т.п.
  ]]></install> 
  
  <uninstall> <![CDATA[ 
//Код для удаления (не обязательно)
//Удаление таблиц из БД, полей и т.п.
  ]]></uninstall>
  
  <hooks>
    
    <hook id="fn_generate_navlinks_end"><![CDATA[
//раскомментируйте ниже только после создания подключаемого файла
//require $ext_info['path'].'/hooks/fn_generate_navlinks_end.php';
    ]]></hook>
    
  </hooks>
</extension>

Скопируйте этот код в файл manifest.xml, сохраните и вы уже можете его установить. Правда, ничего не произойдет, ведь нужно создать хуки и заполнить их кодом. Но расширение уже можно устанавливать и удалять.

Важные поля:

<id>pan_search_advanced</id> - это ID расширения, должно быть уникальным.
<title>Pan Search Advanced</title> - любое имя расширения, назовите как посчитаете нужным.
<version>0.1</version> - версия расширения. Полезно повышать версию при исправлениях, усовершенствовании и добавлении новых функций.

<description>Расширенный поиск</description> - Описание расширения, произвольное.
<author>PunBB</author> - автор расширения
<minversion>1.4.2</minversion> - минимальная версия форумного движка. В данном случае наше расширение будет работать и на старой версии форума 1.3.
<maxtestedon>1.4.4</maxtestedon> - Максимальная разрешенная версия для работы расширения

<dependency>pun_jquery</dependency> - зависимости от расширений, в данном случае расширение это pun_jquery

<note type="install" timing="pre"> - предупреждающее сообщение, в данном случае (type="install") будет появляться каждый раз перед установкой расширения.

3 Reply by PunBB (edited by PunBB 2016.05.15 12:28)

Re: Как написать свое расширение для форума PunBB

Вы наверное заметили, что во всех расширениях, в файле manifest.xml есть хуки, вот такие конструкции:

  <hooks>
    
    <hook id="fn_generate_navlinks_end" priority="5"><![CDATA[
// здесь много - много всякой php лапши
    ]]></hook>
    
  </hooks>

Рассмотрим подробнее.

Несколько важных правил:
Хуки располагаются между открывающим <hooks> и закрывающим </hooks> тегом.
ID хука не должен повторяться id="fn_generate_navlinks_end"

Необязательно:
Вы можете указать приоритет загрузки хуков указав значение в priority="5"

Рекомендации:
Хотя на хуки навешивают огромные куски кода, а многие так и делают, я вам советую подключать файлы в которых находится код превышающий 1 килобайт.
Это полезно тем, что намного проще отслеживать возникшие ошибки, PHP LOG укажет на конкретную строку, а так же не требуется каждый раз обновлять хуки. Правьте код и смотрите результат.
Так как код хуков храниться в БД, то для того, что бы облегчить запросы к БД лучше огромные куски кода размещать в файлах.
Если же в коде выполняются запросы к БД, то лучше вставлять этот код напрямую в сам хук.

Для примера, сравните 2 хука:


ПРИМЕР 1

    <hook id="fn_generate_navlinks_end" priority="5"><![CDATA[
require $ext_info['path'].'/hooks/fn_generate_navlinks_end.php';
    ]]></hook>

В этом случае подключен файл в котором находится огромный кусок кода.
Чтобы облегчить работу с подключаемыми файлами, можно давать им названия в соответствии с ID данного хука. В данном случае имя файла fn_generate_navlinks_end.php.
Все файлы, подключаемые в хуках, для удобства, можно собрать в директорию /hooks/.
ВАЖНО! В начале каждого такого файла необходимо прописывать строку:

<?php

if (!defined('FORUM') ) die();

//Далее исполняемый код

Это не позволит злоумышленникам напрямую обращаться к каким либо файлам.
Ну и конечно не забываем про index.html в корне папки


ПРИМЕР 2

    <hook id="vt_qr_get_topic_info"><![CDATA[
$query['SELECT'] .= ', f.cat_id, c.cat_name';
$query['JOINS'][] = array(
  'LEFT JOIN' => 'categories AS c',
  'ON'        => 'c.id=f.cat_id'
);
    ]]></hook>

Это код добавляет запросы в БД для того, чтобы получить имя категории и ее уникальный ID. Код небольшой и содержащий запрос, поэтому лучше его вставить в сам хук.


ОСОБЕННОСТИ

Когда PHP код вставляете в сам хук символы вызова <?php не нужно.
Но если вы вставляете HTML разметку, то код должен выглядеть так:

    <hook id="fn_generate_navlinks_end" priority="5"><![CDATA[
?>
HTML разметка здесь
<?php
    ]]></hook>

Не оставляйте разметку открытой, хук просто не будет работать.

4 Reply by PunBB (edited by PunBB 2016.04.29 14:23)

Re: Как написать свое расширение для форума PunBB

Итак следуя примеру 1 создаем файл в директории hooks с таким же именем как и имя самого хука /hooks/fn_generate_navlinks_end.php
Вот содержимое файла:

<?php
if (!defined('FORUM')) die();

if ($forum_user['is_guest'])
{
  if ($forum_user['g_read_board'] == '1' && $forum_user['g_search'] == '1')
    $links['search'] = '<li id="navsearch"'.((FORUM_PAGE == 'search') ? ' class="isactive"' : '').'><a href="'.forum_link($forum_url['search_advanced']).'">'.$lang_common['Search'].'</a></li>';
}
else
{
  if (!$forum_user['is_admmod'])
  {
    if ($forum_user['g_read_board'] == '1' && $forum_user['g_search'] == '1')
      $links['search'] = '<li id="navsearch"'.((FORUM_PAGE == 'search') ? ' class="isactive"' : '').'><a href="'.forum_link($forum_url['search_advanced']).'">'.$lang_common['Search'].'</a></li>';
  }
  else
  {
    $links['search'] = '<li id="navsearch"'.((FORUM_PAGE == 'search') ? ' class="isactive"' : '').'><a href="'.forum_link($forum_url['search_advanced']).'">'.$lang_common['Search'].'</a></li>';
  }
}

Сохраняем и подключаем файл в хуке:

    <hook id="fn_generate_navlinks_end" priority="5"><![CDATA[
require $ext_info['path'].'/hooks/fn_generate_navlinks_end.php';
    ]]></hook>

Так же сохраняем. Теперь расширение можно установить и посмотреть в действии PunBB_INFO_ICQ/smile

5 Reply by PunBB

Re: Как написать свое расширение для форума PunBB

Как я уже упомянул, для установки расширения используется тег     

<install>
//Здесь установочный код
</install>

а для удаления расширения тег 

<uninstall><![CDATA[
//Здесь код удаления таблиц, данных и прочее
]]></uninstall>

Установку и удаление можно воспроизводить с помощью кода в подключенных файлах.

Создаем файл install.php

Подключаем его

  <install><![CDATA[
define('PAN_INSTALL', 1);
require $ext_info['path'].'/install.php';
  ]]></install>

Откроем файл install.php и в самом начале вставим

<?php 

if(!defined('PAN_INSTALL')) die();

//здесь параметры установки (создание таблиц и прочего)

По такому же принципу создаем файл uninstall.php

Подключаем

  <uninstall><![CDATA[
define('PAN_UNINSTALL', 1);
require $ext_info['path'].'/uninstall.php';
  ]]></uninstall>

Помещаем код деинсталяции

<?php 

if(!defined('PAN_UNINSTALL')) die();

//код удаления настроек расширения

Обратите внимание на имена констант PAN_INSTALL и PAN_UNINSTALL.
Имена могут быть любыми, в верхнем регистре, латинскими буковками.
Имя константы в манифесте равно имени в файле установки или удаления соответственно.

Проверка if(!defined('PAN_INSTALL')) die(); не позволит установить или удалить расширение при прямом обращении к файлу. Всегда проверяйте константы на существование, это Ваша безопасность.

Успеха! PunBB_INFO_ICQ/smile