Translations of this page: en bg cs de fi fr hu it ja pl ru tr zh

Struct of PunBB development extensions

General information

Система расширений позволяет создавать шибкую систему дополнений, позволяющие создавать дополнения без внесения изменений в ядро PunBB. Управляя системой расширений вы можете определять уровень функциональности, дополняя сайт нужными для вас функциями.

Names of variable, functions

Любые обозначения в коде PunBB имеют свое значение. Систематизация обозначений повышает уровень читаемости и наглядности кода. Принципы обозначения:

  • Любые константы форума пишутся заглавными буквами
  • При указании переменных, содержащих несколько имен, используется в качастве разделителя символ “_”
  $str_name = 'My name is Jake';
 
  • При указании имен переменных, первым словом идет указание какой части форума она принадлежит
echo '<pre>';
  print_r($forum_config);
  echo '</pre>';
 
  • Use common prefixes:
    • num for entities that represent a count
    • cur for entities that represent the current element when iterating through any type of collection (database result set, array etc)
  • При указании имен переменных, касающихся конкертной страницы, используются сокращения. Например, название страницы viewtopic - vt.

Code styles

Уровень читаемости и наглядности кода также придает определенный стиль кодирования, которого придерживаются все участники разработки на протяжении всего кода. И желательно придерживаться того же стиля кодирования, что и на форуме.

  • All line breaks should be LF only.
  • Каждый функциональный блок, который на один уровень глубже, должен отделяться Табуляцией (<tab>):
  for (int $iter = 0; $iter < 10; $iter++)
  {
  <tab>if ($iter < 5)
  <tab>{
  <tab><tab>. . .
  <tab>}
  }
 
  • Математические знаки с двух сторон выделяются пробелами:
  $c = $a + $b;
 
  • При перечислении параметров после символов ”;”, ”,” ставится пробел, но до символа - нет:
  $arr = array('green', 'blue', 'red', 'yellow');
 
  • Каждый функциональный блок отделяется дополнительным символом переноса строки
  • Use common sense. If in doubt, look at similar sections in the PunBB source code.

PHP specification

При написании кода на РНР следует придерживаться нескольких основных моментов написания:

  • Следует использовать <?php, а не укороченный вариант <?
  • Use 'singlequotes' as opposed to “doublequotes” when working with strings
 
  $str = 'Users: '.$num_users;
 
 
//**NOT**//
<code php>
$str = "Users: $num_users";
</code>
  • Use CSRF token with GET/POST date:
    • POST
      • Add hidden csrf_token field to POST-forms
      <input type="hidden" name="csrf_token" value="<?php echo generate_form_token($form_action_link); ?>" />
 
    It is handled automatically in common.php (lines #139-#141)
  * GET
    * Put csrf_token to link to handle it on receiving GET queries
    * Check if $_GET['csrf_token'] is correct on handling action
    * Sample with logout link
      * Generating link
      <code php>
      '<a href="'.pun_link($pun_url['logout'], array($pun_user['id'], generate_form_token('logout'.$pun_user['id']))).'">

<span>'.$lang_common['Logout'].'</span></a>'

      </code>
      * Handling logout action
      <code php>
      if (!isset($_POST['csrf_token']) && (!isset($_GET['csrf_token']) ||

$_GET['csrf_token'] !== generate_form_token('logout'.$pun_user['id'])))

          csrf_confirm_form();
      </code>
* Do not use **$_REQUEST**. Use **$_POST** or **$_GET**
* Do **not** use **require_once** if __FILE__ may not (should not) be ever required (anywhere). Forcing error if __FILE__ was required
* **Leave one line of whitespace** above and below each block of markup, provided the block constitutes multiple lines of markup. I.e. one empty line above each ?> and below each <?php
* Define at page start
  * FORUM_ROOT - relative path to PunBB root dir
  * FORUM_PAGE - current page id

SQL specification

On include/common.php inclusion, the proper implementation of database layer class is being also included according to forum configuration. An instance of this database layer named $forum_db is being created in global scope to provide database helpers.

How to perform a query
  • Direct query. You can simply write an SQL-statement and execute it.
 $result = $forum_db->query('SELECT * FROM topics WHERE id = 10');

Be sure, that your SQL code is cross-compatible with all database engines supported by PunBB.

  • Using query builder. You may transparently build database queries. All the specific of database engines and database structure will automatically be taken in account. Example of usage:
$query = array(
   'SELECT'  => '*',
   'FROM'    => 'topics',
   'WHERE'   => 'id = 10'
);
$result = $forum_db->query_build($query);

See query builder page for details.

How to work with query results

For example, we have this query:

  $query = array(
    'SELECT' => 't.id, t.poster, t.subject, t.posted',
    'FROM'   => 'topics AS t',
    'WHERE'  => 't.forum_id = 1'
  );
  $result = $forum_db->query_build($query) or error(__FILE__, __LINE__);
  • To know how many rows this query returns, use this:
  $forum_db->num_rows($result);
  • To fetch the current row to associative array:
  $data = $forum_db->fetch_assoc($result);
  //An example of getting topic_id
  $topic_id = $data['id'];
  • To fetch the current row to numeric array:
  $data = $forum_db->fetch_row($result);
  //An example of getting topic_id
  $topic_id = $data[0];
  • To fetch only some values from the current row:
  //This code will fetch only the topic id and the topic subject
  list($id,, $subject,) = $forum_db->fetch_row($result);
  • To process all rows in a set you can use this code:
  while ($cur_row = $forum_db->fetch_assoc($result))
  {
    //Actions with $cur_row
  }

The manifest

Manifest in general

Файл манифест представляет из себя основную часть расширения. В нем приписывается работа. Обязательной частью расширения является файл manifest.xml. Он содержит основную идею расширения, реализованная в коде. Файл написан на скриптовом языке XML. Вот пример файла manifest.xml

<?xml version="1.0" encoding="utf-8"?>
 
<extension engine="1.0">
   <id>forum_ext_name</id>
   <title>My best extension</title>
   <version>1.0</version>
   <description>Description of my best extension</description>
   <author>I and I and not so I</author>
   <minversion>1.1</minversion>
   <maxtestedon>2.3.1</maxtestedon>
 
   <note type="install" timing="pre">Примечания при установке, которые обязательны для выполнения. Иначе расширение не будет работать.</note>
   <note type="uninstall" timing="pre">Примечения при удалении. Произойдут действия, которые могут удалить нужные данные.</note>

Как и в HTML, каждый объект, указанный в угловых скобках, называется тег. Они бывают двух видов: открывающие и закрывающие. Теперь рассмотрим весь список обязательных тегов и каждый тег в отдельности со всеми его свойствами.

Blocks of manifest

<extension>

Начальный тег, который объявляет, что начинается расширение и оно будет написано на определенной версии движка. Его единственным параметром является параметр с именем “engine”, обозначающий версию движка XML, на котором работает расширение.

<id>

В теге id указывается краткое имя расширения. Краткое имя расширения должно совпадать с именем папки, из которой запускается расширение. В противном случае будет выдаваться ошибка о несовпадании имен. Все части краткого имени расширения в этом теге разделяются символом “_” и прописываются только в нижнем регистре.

<title>

Тег title содержит полное, официальное имя расширения. В данном теге имя расширения указывается полностью. Ограничения на регистр и тип разделителя не накладывается.

<version>

В этом теге указывается текущая версия расширения. Версия расширения указывается в зависимости от этапа создания.

<description>

В теге description содержится краткое функциональное описание. К примеру, какие действия выполняет расширение и что показывает. Не стоит полностью описывать функциональность расширения. Описывать нужно только главное.

<author>

В теге author указывается имя автора расширения, либо группа авторов, либо команда разработчиков.

<minversion>

Тег minversion указывает минимальную версию PunBB, на которой расширение работает стабильно и с полной функциональностью.

<maxtestedon>

Тег maxtestedon показывает последнюю версию PunBB, на которой проводилось тестирование расширения. Если версия, указанная в теге, не совпадает с текущей версией PunBB, то работа расширения может быть нарушена.

<note>

Тег note описывает возможные сложности при установке расширения. Либо описывает условия, при которых расширение будет работать корректно.

Параметр //**Type**// - это параметр, указывающий примечания, которые следует выводить в конкретном случае. Существует только два значения, которые принимает параметр, - install и uninstall. Рассмотрим их:

* Install - значение параметра type, при котором примечания будут выводится при установке расширения. Следует указывать примечания, касающиеся только установки.
  • Uninstall - значение параметра type, при котором примечания будут выводится при удалении расширения. Следует указывать примечания, касающиеся только удаления.
<dependencies>
<dependency>
<install> and <uninstall>
<hooks>
Parameter "priority" in the tag <hook>

Idea of work extensions

Install extensions

Uninstall extensions

Upgrade extensions (EXT_CUR_VERSION)

Work of extensions on PunBB (hooks)

Including files

Language files

Javascript and CSS

PHP

$ext_info

Steps of development

  • Create the idea of extension
  • Create the wiki article for the extension and write the general idea and the specification there.
  • Add the ticket to the Trac (or just start a text file, if you have no Trac). List the main tasks to complete the extension.
  • //To be invented:// Create the automatic test (e.g. using pun_admin_simpletest) for all the features in your task-list.
  • Code them all! Follow your task-list and strike out done.
    • Commit your changes to the SVN separately: one feature or one bug fix is one commit. Do not commit multiple changes simultaneously.
    • BTW: Use SVN or other VCS. (I personally prefer Bazaar.)
  • Add the documentation to the wiki article.
    • Extension usage.
    • Extension customization and integration.
  • Publish extension in the extension repository (as soon as it passed all the automatic tests).
    • Third-party developers may propose their extensions to be reviewed and published in the repository.
  • Release the extension in Forums.

Recipes


Personal Tools