Differences

This shows you the differences between the selected revision and the current version of the page.

punbb13:extern_ed_pun_ext 2009/07/17 11:17 punbb13:extern_ed_pun_ext 2020/02/06 11:04 current
Line 8: Line 8:
  * Любые константы форума пишутся заглавными буквами   * Любые константы форума пишутся заглавными буквами
  * При указании переменных, содержащих несколько имен, используется в качастве разделителя символ "_"   * При указании переменных, содержащих несколько имен, используется в качастве разделителя символ "_"
-  <code type=php>+  <code php>
  $str_name = 'My name is Jake';   $str_name = 'My name is Jake';
  </code>   </code>
  * При указании имен переменных, первым словом идет указание какой части форума она принадлежит   * При указании имен переменных, первым словом идет указание какой части форума она принадлежит
-  <code type=php> +  <code php>echo '<pre>';
-  echo '<pre>';+
  print_r($forum_config);   print_r($forum_config);
  echo '</pre>';   echo '</pre>';
  </code>   </code>
-  * +  * 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 ==== ==== Code styles ====
 +Уровень читаемости и наглядности кода также придает определенный стиль кодирования, которого придерживаются все участники разработки на протяжении всего кода. 
 +И желательно придерживаться того же стиля кодирования, что и на форуме. 
 +  * All line breaks should be LF only. 
 +  * Каждый функциональный блок, который на один уровень глубже, должен отделяться Табуляцией (<tab>): 
 +  <code php> 
 +  for (int $iter = 0; $iter < 10; $iter++) 
 +  { 
 +  <tab>if ($iter < 5) 
 +  <tab>{ 
 +  <tab><tab>. . . 
 +  <tab>} 
 +  } 
 +  </code> 
 +  * Математические знаки с двух сторон выделяются пробелами: 
 +  <code php> 
 +  $c = $a + $b; 
 +  </code> 
 +  * При перечислении параметров после символов ";", "," ставится пробел, но до символа - нет: 
 +  <code php> 
 +  $arr = array('green', 'blue', 'red', 'yellow'); 
 +  </code> 
 +  * Каждый функциональный блок отделяется дополнительным символом переноса строки 
 +  * Use common sense. If in doubt, look at similar sections in the PunBB source code.
==== PHP specification ==== ==== PHP specification ====
 +При написании кода на РНР следует придерживаться нескольких основных моментов написания:
 +  * Следует использовать <?php, а не укороченный вариант <?
 +  * Use 'singlequotes' as opposed to "doublequotes" when working with strings
 +  <code php>
 +
 +  $str = 'Users: '.$num_users;
 +
 +  </code>
 +
 +  //**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 ==== ==== 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.
 +<code php> $result = $forum_db->query('SELECT * FROM topics WHERE id = 10');</code>
 +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:
 +<code php>$query = array(
 +  'SELECT'  => '*',
 +  'FROM'    => 'topics',
 +  'WHERE'  => 'id = 10'
 +);
 +$result = $forum_db->query_build($query);
 +</code>
 +See [[query builder]] page for details.
 +==== How to work with query results ====
 +For example, we have this query:
 +<code php>
 +  $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__);
 +</code>
 +  * To know how many rows this query returns, use this:
 +<code php>
 +  $forum_db->num_rows($result);
 +</code>
 +  * To fetch the current row to associative array:
 +<code php>
 +  $data = $forum_db->fetch_assoc($result);
 +  //An example of getting topic_id
 +  $topic_id = $data['id'];
 +</code>
 +  * To fetch the current row to numeric array:
 +<code php>
 +  $data = $forum_db->fetch_row($result);
 +  //An example of getting topic_id
 +  $topic_id = $data[0];
 +</code>
 +  * To fetch only some values from the current row:
 +<code php>
 +  //This code will fetch only the topic id and the topic subject
 +  list($id,, $subject,) = $forum_db->fetch_row($result);
 +</code>
 +  * To process all rows in a set you can use this code:
 +<code php>
 +  while ($cur_row = $forum_db->fetch_assoc($result))
 +  {
 +    //Actions with $cur_row
 +  }
 +</code>
====== The manifest ====== ====== The manifest ======
==== Manifest in general ==== ==== Manifest in general ====
 +
 +Файл манифест представляет из себя основную часть расширения. В нем приписывается работа.
 +Обязательной частью расширения является файл manifest.xml. Он содержит основную идею расширения, реализованная в коде. Файл написан на скриптовом языке XML.
 +Вот пример файла manifest.xml
 +
 +<code php>
 +<?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>
 +</code>
 +
 +Как и в HTML, каждый объект, указанный в угловых скобках, называется тег. Они бывают двух видов: открывающие и закрывающие.
 +Теперь рассмотрим весь список обязательных тегов и каждый тег в отдельности со всеми его свойствами.
==== Blocks of manifest ==== ==== Blocks of manifest ====
== <extension> == == <extension> ==
 +
 +Начальный тег, который объявляет, что начинается расширение и оно будет написано на определенной версии движка.
 +Его единственным параметром является параметр с именем "engine", обозначающий версию движка XML, на котором работает расширение.
== <id> == == <id> ==
 +
 +В теге id указывается краткое имя расширения. Краткое имя расширения должно совпадать с именем папки, из которой запускается расширение.
 +В противном случае будет выдаваться ошибка о несовпадании имен.
 +Все части краткого имени расширения в этом теге разделяются символом "_" и прописываются только в нижнем регистре.
== <title> == == <title> ==
 +
 +Тег title содержит полное, официальное имя расширения.
 +В данном теге имя расширения указывается полностью. Ограничения на регистр и тип разделителя не накладывается.
== <version> == == <version> ==
 +
 +В этом теге указывается текущая версия расширения.
 +Версия расширения указывается в зависимости от этапа создания.
== <description> == == <description> ==
 +
 +В теге description содержится краткое функциональное описание. К примеру, какие действия выполняет расширение и что показывает.
 +Не стоит полностью описывать функциональность расширения. Описывать нужно только главное.
== <author> == == <author> ==
 +
 +В теге author указывается имя автора расширения, либо группа авторов, либо команда разработчиков.
== <minversion> == == <minversion> ==
 +
 +Тег minversion указывает минимальную версию PunBB, на которой расширение работает стабильно и с полной функциональностью.
== <maxtestedon> == == <maxtestedon> ==
 +
 +Тег maxtestedon показывает последнюю версию PunBB, на которой проводилось тестирование расширения.
 +Если версия, указанная в теге, не совпадает с текущей версией PunBB, то работа расширения может быть нарушена.
== <note> == == <note> ==
-== Install ==+Тег note описывает возможные сложности при установке расширения. Либо описывает условия, при которых расширение будет работать корректно.
-== Uninstall ==+  Параметр //**Type**// - это параметр, указывающий примечания, которые следует выводить в конкретном случае. Существует только два значения, которые принимает параметр, - install и uninstall. Рассмотрим их: 
 +   
 +  * Install - значение параметра type, при котором примечания будут выводится при установке расширения. Следует указывать примечания, касающиеся только установки.
-== Type ==+  * Uninstall - значение параметра type, при котором примечания будут выводится при удалении расширения. Следует указывать примечания, касающиеся только удаления.
== <dependencies> == == <dependencies> ==
Line 88: Line 258:
  * Create the idea of extension   * Create the idea of extension
  * Create the wiki article for the extension and write the general idea and the specification there.   * Create the wiki article for the extension and write the general idea and the specification there.
-    * The page url must be http://punbb.informer.com/wiki/punbb13:<extension_id>, e.g. http://punbb.informer.com/wiki/punbb13:pun_pm.+    * The page url must be https://punbb.informer.com/wiki/punbb13:<extension_id>, e.g. https://punbb.informer.com/wiki/punbb13:pun_pm.
    * You may also start the discussion in Forums to ask users to add their feature requests to the specification.     * You may also start the discussion in Forums to ask users to add their feature requests to the specification.
  * 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.   * 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.

Personal Tools