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 php>
$str = "Users: $num_users";
</code>
* Use CSRF token with GET/POST date:
  * POST
    * Add hidden csrf_token field to POST-forms
    <code 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 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

Database helpers

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 (FIXME make it more informative):
$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

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