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

This is an old revision of the document!


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 type=php>
$str = "Users: $num_users";
</code>
* Use CSRF token with GET/POST date:
  * POST
    * Add hidden csrf_token field to POST-forms
    <code type=php>
    <input type="hidden" name="csrf_token" value="<?php echo generate_form_token($form_action_link); ?>" />
    </code>
    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 type=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 type=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

The manifest

Manifest in general

Blocks of manifest

<extension>
<id>
<title>
<version>
<description>
<author>
<minversion>
<maxtestedon>
<note>
Install
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