Руководство по написанию программного кода для phpBB3 (Олимпус)

Здесь изложены основные правила написания кода для phpBB «Олимпус», которые рекомендуется соблюдать как можно точнее.

[url=http://www.phpbbguru.net/useful/codebook/coding-guidelines/]Руководство по написанию программного кода[/url]

Основные положения 
Настройки редактора
Заголовок файла
Расположение файлов
Оформление кода, рекомендации
Названия переменных и функций
Оформление кода
Оформление SQL
Оптимизация
Общие рекомендации
Работа со стилями
Файлы конфигурации стилей
Общие правила работы со стилями
Работа с шаблонами
Общие правила работы с шаблонами
Наследование шаблонов
Наборы символов и кодировки
Правила перевода (интернационализация, локализация)
Стандартизация
Другие положения
Стиль написания
История версий данного руководства
Авторское право и отказ от ответственности

1. Основные положения

1.i. Настройки редактора

Отступы и пробелы:

Чтобы максимально всё упростить, мы будем использовать вместо пробелов отступы (табуляцию). Мы рекомендуем принять 4 (четыре) пробела за один символ табуляции, поэтому вам нужно установить ширину табуляции в 4 пробела в своем редакторе. Убедитесь, что при сохранении файла редактор сохраняет табуляцию и не преобразует ее в пробелы. Таким образом, наш код будет отображаться так, как мы хотим, без нарушений форматирования текущих файлов.

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

{TAB}$mode{TAB}{TAB}= request_var('mode', '');
{TAB}$search_id{TAB}= request_var('search_id', '');

Если в коде использованы символы табуляции (обозначены знаком {TAB}), то оба знака равенства должны находиться в одном и том же столбце.

Переводы строк:

Убедитесь, что ваш редактор сохраняет файлы в формате перевода строк UNIX (LF). Это означает, что строки должны оканчиваться только символом перевода строки, а не в формате перевода строк Windows (комбинация CR/LF), используемый в Win32, или в формате перевода строк Classic Mac (CR). Любой достойный редактор должен уметь это делать, но не всегда эта настройка установлена по умолчанию. Изучите ваш редактор. Если вам нужен совет по использованию редактора для вашей операционной системы, попросите помощи у кого-нибудь из разработчиков. Некоторые из них работают в Win32.

1.ii. Заголовок файла

Стандартный заголовок для новых файлов:

Этот шаблон заголовка должен присутствовать в начале каждого файла phpBB:

/**
*
* @package {НАЗВАНИЕ ПАКЕТА}
* @version $Id: $
* @copyright (c) 2007 phpBB Group
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*
*/

См. раздел Расположение файлов для получения информации о правильном названии пакета.

Файлы, содержащие управляющий код (inline code):

/**
* {ЗАГОЛОВОК}
*/

/**
*/
{КОД}

Файлы, содержащие только функции:

Не забывайте документировать, снабжая комментариями, функции (особенно первую функцию, следующую за заголовком файла). Каждая функция должна иметь, по крайней мере, комментарий о том, что эта функция делает. Для более сложных функций рекомендуется также документировать и аргументы.

Файлы, содержащие только классы:

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

Код, следующий за заголовком в файлах с функциями или классами:

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

/**
* {ЗАГОЛОВОК}
*/

/**
* @ignore
*/
Небольшой кусочек кода, вроде одного — двух определений или условий

/**
* {ДОКУМЕНТАЦИЯ}
*/
class ...

1.iii. Расположение файлов

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

phpBB3

Основные файлы и все файлы, не выделенные в отдельный пакет

acm

/includes/acm, /includes/cache.php

Система кэширования

acp
/adm, /includes/acp, /includes/functions_admin.php
Администраторский раздел

dbal
/includes/db
Инструментарий работы с базой данных.
Базовый класс — dbal

/includes/db/dbal.php
Базовый класс инструментария, определяющий основную структуру и некоторые общие определения

/includes/db/firebird.php
Инструментарий базы данных Firebird/Interbase

/includes/db/msssql.php
Инструментарий базы данных MSSQL

/includes/db/mssql_odbc.php
Инструментарий базы данных MSSQL ODBC для MSSQL

/includes/db/mysql.php
Инструментарий базы данных MySQL для MySQL 3.x/4.0.x/4.1.x/5.x

/includes/db/mysqli.php
Инструментарий базы данных MySQLi

/includes/db/oracle.php
Инструментарий базы данных Oracle

/includes/db/postgres.php
Инструментарий базы данных PostgreSQL

/includes/db/sqlite.php
Инструментарий базы данных Sqlite

diff
/includes/diff
Модуль Diff

docs
/docs
Документация phpBB

images
/images
Все глобальные изображения, не связанные со стилями

install
/install
Система установки

language
/language
Все языковые файлы

login
/includes/auth
Модули аутентификации

VC
/includes/captcha
CAPTCHA (визуальное подтверждение)

mcp
mcp.php, /includes/mcp, report.php
Модераторский раздел

ucp
ucp.php, /includes/ucp
Личный раздел

utf
/includes/utf
Функции и классы, связанные с UTF-8

search
/includes/search, search.php
Система поиска

styles
/styles, style.php
Стили, шаблоны, темы и наборы изображений phpBB

 Наверх

2. Оформление кода, рекомендации

Обратите внимание, что данные рекомендации касаются всех файлов php, html, javascript и css.

2.i. Названия переменных и функций

Мы не будем использовать ни одну из форм венгерской нотации. Многие из нас считают, что венгерская нотация — это один из основных способов запутывания кода, широко используемых в настоящее время.

Названия переменных:

Названия переменных должны быть выполнены в нижнем регистре, слова следует разделять знаком подчеркивания, например:

$current_user  — верно, а вот $currentuser и $currentUser  — неверно.

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

Индексы в циклах:

Единственная ситуация, при которой допустимо использовать название переменной из одного символа, — это когда она является индексом в некоторой циклической конструкции. В таком случае, индекс внешнего цикла всегда должен быть $i. Если цикл находится внутри другого цикла, то его индекс должен быть $j, следующий — $k и так далее. Это правило не относится к тем случаям, когда в качестве индекса используется некоторая уже существующая переменная со значащим названием. Пример:

for ($i = 0; $i < $outer_size; $i++)
{
   for ($j = 0; $j < $inner_size; $j++)
   {
      foo($i, $j);
   }
}

Названия функций:

Функции также должны быть названы содержательно. Мы не программируем на языке C и мы не хотим давать функциям имена наподобие «stristr()». Напомним, названия должны быть написаны в нижнем регистре, все слова разделены знаком подчеркивания. Желательно, чтобы названия функций имели глагол в своем составе. Примерами хороших названий могут послужить следующие: print_login_status(), get_user_data() и так далее.

Аргументы функций:

Аргументы подчиняются тем же самым правилам, что и названия переменных. Нам не нужен десяток функций наподобие такой: do_stuff($a, $b, $c). В большинстве случаев мы бы хотели иметь возможность понять, как использовать функцию, просто лишь взглянув на ее объявление.

Вывод: Основная идея — не приносить ясность кода в жертву лени. Всё должно балансироваться здравым смыслом; print_login_status_for_a_given_user() — это название слишком громоздкое, функцию лучше назвать так: print_user_login_status() или просто print_login_status() .

Специальные наименования: 

Для обозначения всех смайлов используется термин smiley в единственном числе и smilies во множественном.

2.ii. Оформление кода

Всегда ставьте фигурные скобки:

Это еще один случай, когда не напечатанные из-за лени два дополнительных символа ухудшают читаемость кода. Даже если тело какой-то конструкции состоит всего из одной строки, не опускайте скобки. Ни в коем случае! Примеры:

// Здесь неправильно.

if (condition) do_stuff();

if (condition)
	do_stuff();

while (condition)
	do_stuff();

for ($i = 0; $i < size; $i++)
	do_stuff($i);

 // Здесь правильно. 

if (condition)
{
	do_stuff();
}

while (condition)
{
	do_stuff();
}

for ($i = 0; $i < size; $i++)
{
	do_stuff();
}

Где размещать фигурные скобки:

Это что-то вроде священной войны, но мы используем следующий стиль: фигурные скобки всегда расположены в отдельной строке. Закрывающая скобка всегда должна быть в том же столбце, что и соответствующая ей открывающая скобка, например:

if (condition)
{
	while (condition2)
	{
		...
	}
}
else
{
	...
}

for ($i = 0; $i < $size; $i++)
{
	...
}

while (condition)
{
	...
}

function do_stuff()
{
	...
}

Ставьте пробелы между лексемами:

Это еще один простой и легкий способ содержать код в читаемом виде без особых усилий. Когда вы пишете присвоение, выражение и т. д., всегда ставьте один пробел между лексемами. Другими словами, пишите код так, как если бы он был английским языком. Помещайте пробелы между переменными и операторами. Не помещайте пробелы сразу же за открывающей скобкой или перед закрывающей. Не помещайте пробелы перед запятой или точкой с запятой. Лучшим образом всё наглядно объясняют следующие примеры:

// Каждая пара содержит сначала неверное написание, затем верное.

$i=0;
$i = 0;

if($i<7) ...
if ($i < 7) ...

if ( ($i < 7)&&($j > 8) ) ...
if ($i < 7 && $j > 8) ...

do_stuff( $i, 'foo', $b );
do_stuff($i, 'foo', $b);

for($i=0; $i<$size; $i++) ...
for ($i = 0; $i < $size; $i++) ...

$i=($j < $size)?0:1;
$i = ($j < $size) ? 0 : 1;

Приоритет операторов:

Вы знаете точные сведения о приоритете всех операторов в PHP? И я тоже не знаю. Не пытайтесь угадать. Всегда вносите очевидность, используя круглые скобки в выражениях, чтобы точно понять приоритет выполнения операторов. Однако, не злоупотребляйте скобками, чтобы не ухудшить читаемость кода. То есть не используйте скобки в простых и понятных выражениях. Примеры:

// какой будет результат? кто знает?
$bool = ($i < 7 && $j > 8 || $k == 4);


// теперь вы будете уверены, каков будет результат.
$bool = (($i < 7) && (($j < 8) || ($k == 4)));


// Но этот вариант самый лучший, поскольку он и на глаз понятнее, и суть ясна
$bool = ($i < 7 && ($j < 8 || $k == 4));

Выделение строк кавычками:

В PHP существуют два разных способа выделения строк кавычками: или одиночными кавычками, или двойными. Основное отличие состоит в том, что обработчик выполняет интерполяцию переменных в строках с двойными кавычками и не делает этого в строках с одиночными кавычками. Поэтому вам следует всегда использовать одиночные кавычки, кроме случаев, когда вам нужна интерполяция переменных в строке. Таким образом, мы предотвращаем разбор десятков строк обработчиком в тех строках, где интерполяция не требуется.

Кроме того, если вы используете строковую переменную как часть вызова функции, то не нужно обрамлять переменную кавычками. Опять же, это заставляет обработчик строк проделывать бесполезную работу. Однако, обратите внимание, что почти все обозначения спецсимволов, предваряемые символом обратной косой черты, которые существуют для использования внутри двойных кавычек, не будут работать в строках с одиночными кавычками. Будьте внимательны и не бойтесь нарушать это правило, если код будет выглядеть проще для чтения. Примеры:

// неверное написание

$str = "Это очень длинная строка, где отсутствуют переменные, которые обработчик строк мог бы найти.";

do_stuff("$str");

$str = 'Это очень длинная строка, где отсутствуют переменные, которые обработчик строк мог бы найти.';

do_stuff($str);

// Иногда одиночные кавычки неуместны
$post_url = $phpbb_root_path . 'posting.' . $phpEx . '?mode=' . $mode . '&start=' . $start;


// Двойные кавычки иногда необходимы, чтобы не перегружать строку конкатенацией
$post_url = "{$phpbb_root_path}posting.$phpEx?mode=$mode&start=$start";


В запросах SQL отчасти допускается смешивание двойных и одиночных кавычек (согласно правилам касательно оформления SQL), во всех остальных случаях предпочтительно использовать только один стиль — главным образом, одиночные кавычки.

Ключи ассоциативных массивов:

В PHP можно использовать в качестве ключей ассоциативного массива строки, не заключенные в кавычки. Мы не используем такой способ — строка всегда должна быть заключена в кавычки, чтобы избежать недоразумений. Обратите внимание, что это правило применимо только когда мы используем литерал, а не переменную. Примеры:

// неверно

$foo = $assoc_array[blah];

// верно

$foo = $assoc_array['blah'];

// неверно

$foo = $assoc_array["$var"];

// верно

$foo = $assoc_array[$var];

Комментарии:

Каждая сложная функция должна быть снабжена комментарием, который описывает программисту всё, что ему нужно о ней знать. Значение каждого параметра, ожидаемые входные и возвращаемые данные — вот тот минимум, который требуется для такого комментария. Также должно быть представлено поведение функции в случае ошибок (и что это за случаи) — как правило, это входит в комментарий о возвращаемых значениях.

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

Избегайте использования блочных комментариев /* */ для одной — двух строк: для них должен использоваться такой способ: // .

«Волшебные» числа:

Не используйте их. Применяйте именованные константы для каждого значения литерала, кроме особых очевидных случаев. Другими словами, использовать проверку на то, что массив имеет 0 элементов, используя литерал 0, — это нормально. Но ненормальным является присвоение какого-то особого значения числу и дальнейшее использование его везде в качестве литерала. Это идет в ущерб читаемости и удобства дальнейшей работы с кодом. Константы true и false должны использоваться вместо литералов 0 и 1: даже несмотря на то что они имеют одни и те же значения (но не тип!), логику программы намного легче понять, если вы используете именованные константы. Приводите типы данных, где это необходимо, не полагайтесь на автоматическое приведение (в настоящее время PHP очень слабо работает с типами данных, что может привести к проблемам безопасности, если разработчик не уделяет этому должное внимание).

Сокращенные операторы:

Единственные сокращенные операторы, которые могут вызвать проблему с легкостью чтения кода, — это операторы инкремента $i++ и декремента $j--. Эти операторы не следует использовать в качестве частей выражений. Однако, они могут быть использованы отдельной строкой. Использование этих операторов в выражениях просто не стоит тех проблем, которые могут возникнуть при отладке. Например:

// неверно

$array[++$i] = $j;
$array[$i++] = $k;

 // верно  

$i++;
$array[$i] = $j;

$array[$i] = $k;
$i++;

Условия, используемые внутри строки:

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

// Неудачное место для их использования

($i < $size && $j > $size) ? do_stuff($foo) : do_stuff($bar);

$min = ($i < $j) ? $i : $j;

Не используйте неинициализированные переменные.

В phpBB3 мы используем более высокий уровень сообщения об ошибках времени исполнения. Это значит, что использование неинициализированных переменных вызовет предупреждение. Эти предупреждения можно избежать, если использовать встроенную функцию isset() для проверки того, была ли установлена переменная или нет — но лучше всегда инициализировать переменные. Эта функция может пригодиться в том случае, если требуется проверить, существует ли ключ в массиве, например:

// Неверно

if ($forum) ...

// Верно  

if (isset($forum)) ...

if (isset($forum) && $forum == 5)

Функция empty() полезна в том случае, если вы хотите проверить, не была ли установлена переменная или пустая ли она (пустая строка, 0 как строка или число, NULL, false, пустой массив или переменная класса, объявленная, но не имеющая значения). Таким образом, empty следует использовать вместо isset($array) && sizeof($array) > 0 — такой код можно написать короче: !empty($array).

Оператор switch:

Блоки switch/case иногда могут быть очень длинными. Чтобы иметь понятный код, к таким блокам, а также операторам break тоже необходимо применять правило расположения фигурных скобок (расположение в отдельных строках, но строго друг под другом). Пример:

// Неверно

switch ($mode)
{
	case 'mode1':
		// Я что-то здесь делаю
		break;
	case 'mode2':
		// Здесь я делаю что-то другое
		break;
}

switch ($mode)
{
	case 'mode1':
		// Я что-то здесь делаю
	break;

	case 'mode2':
		// Здесь я делаю что-то другое
	break;

	default:
		// Всегда допускайте, что ни один из вышеописанных case не выполнился
	break;
}

switch ($mode)
{
	case 'mode1':

		// Я что-то здесь делаю

	break;

	case 'mode2':

		// Здесь я делаю что-то другоe

	break;

	default:

		// Всегда допускайте, что ни один из вышеописанных case не выполнилсяt

	break;
}

switch ($mode)
{
	case 'mode1':

		// Я что-то здесь делаe

	// no break here

	case 'mode2':

		// Здесь я делаю что-то другоe

	break;

	default:

		// Всегда допускайте, что ни один из вышеописанных case не выполнился

	break;
} 

2.iii. Оформление SQL

Общие правила оформления SQL:

Все запросы SQL должны быть совместимы со всеми поддерживаемыми СУБД. Если используется SQL, специфичный для определенной СУБД, то должны быть предоставлены альтернативные запросы для остальных СУБД (MySQL3/4/5, MSSQL (7.0 и 2000), PostgreSQL (7.0+), Firebird, SQLite, Oracle8, ODBC (обобщенный, если возможно).

Все команды SQL должны использовать инструментарий работы с базой данных (DBAL)

Оформление кода SQL:

Выражения SQL часто нечитаемы, если не применять некоторые правила форматирования. Это происходит из за того, что они порой становятся очень громоздкими. Тем не менее, форматирование запросов SQL значительно повышает удобство чтения кода. SQL-запросы должны быть отформатированы следующим образом, основываясь на ключевых словах:

$sql = 'SELECT *
<-один отступ->FROM ' . SOME_TABLE . '
<-один отступ->WHERE a = 1
<- два отступа ->AND (b = 2
<-  три отступа  ->OR b = 3)
<-один отступ->ORDER BY b'

$sql = 'SELECT *
	FROM ' . SOME_TABLE . '
	WHERE a = 1
		AND (b = 2
			OR b = 3)
	ORDER BY b';

Кавычки и SQL: 

Используйте двойные кавычки там, где это применимо (переменные в следующих примерах заранее были приведены к целому типу). Примеры: 

// Неверно.

"UPDATE " . SOME_TABLE . " SET something = something_else WHERE a = $b";

'UPDATE ' . SOME_TABLE . ' SET something = ' . $user_id . ' WHERE a = ' . $something;

 // Верно. 

'UPDATE ' . SOME_TABLE . " SET something = something_else WHERE a = $b";

'UPDATE ' . SOME_TABLE . " SET something = $user_id WHERE a = $something";

Избегайте запросов SQL, специфичных для определенных СУБД:

Оператор «не равно», в соответствии со стандартом SQL:2003, — это „<>“

// Неверный пример.

$sql = 'SELECT *
	FROM ' . SOME_TABLE . '
	WHERE a != 2';

$sql = 'SELECT *
	FROM ' . SOME_TABLE . '
	WHERE a <> 2';

Общие методы DBAL: 

sql_escape():

Всегда используйте $db->sql_escape()  для проверки строки в выражении SQL (даже если вы уверены, что ваша строка не содержит одиночных кавычек, никогда не доверяйте входным данным), например:

$sql = 'SELECT *
	FROM ' . SOME_TABLE . "
	WHERE username = '" . $db->sql_escape($username) . "'";

sql_build_array():

При необходимости обновить или вставить данные (команды UPDATE и INSERT соответственно) используйте функцию $db->sql_build_array() . Эта функция уже экранирует строки и проверяет другие типы, так что здесь нет необходимости этого делать. Вставляемые данные должны быть представлены в виде массива — $sql_ary — или прямо внутри выражения, если нужно вставить или обновить одну или две переменные. Пример вставки данных:

$sql_ary = array(
	'somedata'		=> $my_string,
	'otherdata'		=> $an_int,
	'moredata'		=> $another_int
);

$db->sql_query('INSERT INTO ' . SOME_TABLE . ' ' . $db->sql_build_array('INSERT', $sql_ary));

$sql_ary = array(
	'somedata'		=> $my_string,
	'otherdata'		=> $an_int,
	'moredata'		=> $another_int
);

$sql = 'UPDATE ' . SOME_TABLE . '
	SET ' . $db->sql_build_array('UPDATE', $sql_ary) . '
	WHERE user_id = ' . (int) $user_id;
$db->sql_query($sql);

sql_multi_insert():

Если вы хотите вставить несколько выражений за один раз, используйте отдельный метод sql_multi_insert(). Пример:

$sql_ary = array();

$sql_ary[] = array(
	'somedata'		=> $my_string_1,
	'otherdata'		=> $an_int_1,
	'moredata'		=> $another_int_1,
);

$sql_ary[] = array(
	'somedata'		=> $my_string_2,
	'otherdata'		=> $an_int_2,
	'moredata'		=> $another_int_2,
);

$db->sql_multi_insert(SOME_TABLE, $sql_ary);

$sql = 'SELECT *
	FROM ' . FORUMS_TABLE . '
	WHERE ' . $db->sql_in_set('forum_id', $forum_ids);
$db->sql_query($sql);

SELECT FROM phpbb_forums WHERE forum_id IN (1, 2, 3)


// SQL-выражение, если $forum_ids = array(1) или $forum_ids = 1

SELECT FROM phpbb_forums WHERE forum_id = 1


Естественно, то же самое возможно и с выполнением выборки при несовпадении ни с одним из ряда значений:

$sql = 'SELECT *
	FROM ' . FORUMS_TABLE . '
	WHERE ' . $db->sql_in_set('forum_id', $forum_ids, true);
$db->sql_query($sql);

SELECT FROM phpbb_forums WHERE forum_id NOT IN (1, 2, 3)

// SQL-выражение, если $forum_ids = array(1) или $forum_ids = 1

SELECT FROM phpbb_forums WHERE forum_id <> 1

Если предоставленный массив пуст, результатом будет ошибка.

sql_build_query():

Функция $db->sql_build_query()  предназначена для построения SQL-выражений запросов SELECT и SELECT DISTINCT, если вам необходимо объединить результат (команда JOIN) нескольких таблиц или в случае выборки из нескольких таблиц с присоединением (JOIN). Использование функции необходимо для того, чтобы удостовериться в работоспособности итогового выражения во всех поддерживаемых СУБД. Вместо объяснения каждого возможного случая лучше предоставить небольшой пример:

$sql_array = array(
	'SELECT'	=> 'f.*, ft.mark_time',

	'FROM'		=> array(
		FORUMS_WATCH_TABLE	=> 'fw',
		FORUMS_TABLE		=> 'f'
	),

	'LEFT_JOIN'	=> array(
		array(
			'FROM'	=> array(FORUMS_TRACK_TABLE => 'ft'),
			'ON'	=> 'ft.user_id = ' . $user->data['user_id'] . ' AND ft.forum_id = f.forum_id'
		)
	),

	'WHERE'		=> 'fw.user_id = ' . $user->data['user_id'] . '
		AND f.forum_id = fw.forum_id',

	'ORDER_BY'	=> 'left_id'
);

$sql = $db->sql_build_query('SELECT', $sql_array);

$sql_array = array(
	'SELECT'	=> 'f.*',

	'FROM'		=> array(
		FORUMS_WATCH_TABLE	=> 'fw',
		FORUMS_TABLE		=> 'f'
	),

	'WHERE'		=> 'fw.user_id = ' . $user->data['user_id'] . '
		AND f.forum_id = fw.forum_id',

	'ORDER_BY'	=> 'left_id'
);

if ($config['load_db_lastread'])
{
	$sql_array['LEFT_JOIN'] = array(
		array(
			'FROM'	=> array(FORUMS_TRACK_TABLE => 'ft'),
			'ON'	=> 'ft.user_id = ' . $user->data['user_id'] . ' AND ft.forum_id = f.forum_id'
		)
	);

	$sql_array['SELECT'] .= ', ft.mark_time ';
}
else
{
	// Here we read the cookie data
}

$sql = $db->sql_build_query('SELECT', $sql_array);

2.iv. Оптимизация

Определения в цикле:

Всегда старайтесь оптимизировать ваши циклы, не допуская выполнения операций в условиях цикла, поскольку эти условия проверяются на каждом шаге цикла. Для присваиваний следует использовать содержательные имена. Пример:

// На каждом шаге цикла будет вызвана функция sizeof

for ($i = 0; $i < sizeof($post_data); $i++)
{
	do_something();
}

 // Вы можете присвоить неизменяемый результат прямо внутри определения цикла 

for ($i = 0, $size = sizeof($post_data); $i < $size; $i++)
{
	do_something();
}

Использование in_array(): 

Старайтесь избегать использования in_array() для очень больших массивов, а также старайтесь не помещать их в циклы, если обрабатываемый массив состоит из более чем 20 элементов. in_array() может отнять много времени на выполнение, а также использовать много ресурсов процессора. Для маленьких обработок это незаметно, но если используется большой массив в цикле, то такие обработки сами по себе могут занимать до нескольких секунд времени. Если вам требуется данная функциональность, то используйте isset() для ключей массивов, перенося значения на место ключей и наоборот. Например, вызов isset($array[$var])  сработает значительно быстрее, чем in_array($var, array_keys($array)) .

2.v. Общие рекомендации

Общие положения:

Никода не доверяйте пользовательскому вводу (это правило распространяется и на серверные переменные, и на cookies).

Старайтесь проверять значения, возвращенные функциями.

Старайтесь проверять переданные в функцию аргументы внутри этой самой функции.

Класс auth должен использоваться для всех проверок авторизации.

Категорически не следует удалять любую информацию об авторских правах (как содержащуюся в исходном коде, так и отображаемую на экране как результат работы кода), а также не следует изменять эту информацию никаким образом (можно лишь дополнять).

Переменные:

Используйте функцию request_var(), за исключением ввода или проверки единичного параметра. 

Функция request_var определяет устанавливаемый тип данных из второго параметра (который также определяет и значение по умолчанию). Если вам нужно получить переменную скалярного типа, то вы должны сообщить это явно функции request_var. Примеры:

// Старый метод, не используйте его

$start = (isset($HTTP_GET_VARS['start'])) ? intval($HTTP_GET_VARS['start']) : intval($HTTP_POST_VARS['start']);
$submit = (isset($HTTP_POST_VARS['submit'])) ? true : false;

$start = request_var('start', 0);
$submit = (isset($_POST['submit'])) ? true : false;

$start = request_var('start', '0');

$mark_array = request_var('mark', array(0));

$action_ary = request_var('action', array('' => 0));

Проверки входа, перенаправление: 

Чтобы отобразить форму входа на форум, используйте login_forum_box($forum_data) , иначе — функцию login_box().

Функция login_box() может иметь первый параметр, указывающий на перенаправление. Указывайте пустую строку в том случае, если вы хотите перенаправить пользователя на его текущее местоположение, в остальных случаях не добавляйте $SID к строке перенаправления (например, на странице «Личный раздел > Вход» мы перенаправляем на главную страницу конференции, иначе пользователь был бы перенаправлен на страницу входа).

Ответственные операции:

Для ответственных операций всегда позволяйте пользователю подтвердить свое действие. Для отображения подтверждения используйте функцию confirm_box().

Операции изменения:

При выполнении операций, вносящих изменения в базу данных, например, при отправке сообщения, всегда проверяйте идентификатор формы, за исключением случая использования confirm_box(). Для этого вызывайте функции add_form_key() и check_form_key().

	add_form_key('my_form');

	if ($submit)
	{
		if (!check_form_key('my_form'))
		{
			trigger_error('FORM_INVALID');
		}
	}

Сессии: 

Сессии должны начинаться на каждой странице, максимально близко к началу, используя следующий код:

$user->session_begin();
$auth->acl($user->data);
$user->setup();

Ошибки и сообщения:

Все сообщения и ошибки должны отображаться при помощи вызов функции trigger_error(), используя соответствующий тип сообщения и языковую строку. Примеры:

trigger_error('NO_FORUM');
	
trigger_error($user->lang['NO_FORUM']);
	
trigger_error('NO_MODE', E_USER_ERROR);

Форматирование URL

Все URL, указывающие на внутренние файлы, должны предваряться переменной $phpbb_root_path. В администраторском разделе все URL, указывающие на внутренние файлы, должны предваряться переменной $phpbb_admin_path. Это гарантирует правильность пути, а также позволяет администратору просто переименовать папку администраторского раздела, оставляя сам раздел работающим как прежде (хотя некоторые ссылки перестанут работать и потребуются небольшие изменения в коде).

Функция append_sid(), появившаяся в версии 2.0.x, всё также доступна, хотя она не управляет изменениями в URL автоматически. Взгляните на документацию к коду, если вы хотите получить более подробные сведения по использованию append_sid(). Пример вызова функции append_sid():

append_sid("{$phpbb_root_path}memberlist.$phpEx", 'mode=group&g=' . $row['group_id'])

Использование общих функций: 

Из данных функций выбраны только какие-то определенные из-за индивидуальных предпочтений: кроме как единства в коде, других преимуществ они не дают.

• Используйте sizeof  вместо count
• Используйте strpos  вместо strstr
• Используйте else if  вместо elseif
• Используйте false  (в нижнем регистре) вместо FALSE
• Используйте true  (в нижнем регистре) вместо TRUE

Завершение работы

Ваша страница должна вызывать либо page_footer() в конце, чтобы обработать вывод шаблона и завершить работу скрипта, или, по крайней мере, вызывать exit_handler(). Этот вызов необходим потому, что он вызывает внешние приложения, присоединенные к phpBB, необходимые для выполнения в конце работы скрипта.

Наверх

3. Работа со стилями

3.i. Файлы конфигурации стилей

Файлы конфигурации стилей представляют собой обычные списки «имя — значение» с информацией, необходимой для установки стиля. Похожие файлы конфигурации существуют для шаблонов, тем и наборов изображений. Все они построены по одному и тому же принципу и не будут представлены каждый отдельно. Стили могут использовать установленные компоненты при помощи элементов required_theme, required_template и required_imageset. Важная часть файла конфигурации стиля — это использование уникального имени.

        # Общая информация по данному стилю
        name = prosilver_duplicate
        copyright = © phpBB Group, 2007
        version = 3.0.3
        required_template = prosilver
        required_theme = prosilver
        required_imageset = prosilver

 3.ii. Общие правила работы со стилями

Шаблоны должны быть написаны в единообразном стиле. В подходящих случаях они должны быть основаны на существующих экземплярах, например, index, viewforum или viewtopic (сочетание которых образует ряд форм условий и переменных). Также обратите внимание, что правила написания кода применяются и к шаблонам там, где это возможно.

Внешний класс таблицы forumline заменен на tablebg.

При написании <table> порядок <table class="" cellspacing="" cellpadding="" border="" align=""> создает единство и позволяет каждому легко понять, какая таблица как будет выглядеть. То же самое относится и к большинству других тегов, для которых могут быть установлены дополнительные параметры; единство — главная цель в таких случаях.

Каждый элемент блочного уровня должен быть сдвинут на один символ табуляции, то же самое и для табличных элементов, таких как <tr> <td> и так далее, но положение элемента <table> и последующего (и закрывающего) <tr> должны быть друг под другом, в одной колонке. Конечно, это не распространяется на элементы div.

Не используйте <span> чаще, чем необходимо... CSS работает таким образом, что размеры текста зависят от родительского класса. Так что запись <span class="gensmall"><span class="gensmall">TEST</span></span>  приведет в итоге к очень маленькому тексту. Подобным же образом, не используйте span совсем, если другой элемент может содержать определение класса, например:

<td><span class="gensmall">TEST</span></td>

<td class="gensmall">TEST</td>

<!-- BEGIN test -->
	<tr>
		<td>{test.TEXT}</td>
	</tr>
<!-- END test -->

<!-- BEGIN test -->
<tr>
	<td>{test.TEXT}</td>
</tr>
<!-- END test -->

Наверх

4. Работа с шаблонами

4.i. Общие правила работы с шаблонами

Именование файлов

Во-первых, теперь шаблоны имеют расширение «.html» вместо прежнего «.tpl». Это было сделано для того, чтобы упростить жизнь некоторым людям в отношении подсветки синтаксиса и т. д.

Переменные

Все переменные шаблона должны быть названы в соответствии с правилами (используя знаки подчеркивания вместо пробелов), языковые элементы должны предваряться приставкой L_, системные данные — S_, URL — U_, JavaScript URL — UA_, языковые строки, вставляемые в выражения JavaScript, — LA_, все остальные переменные должны быть представлены «как есть».

Шаблонные переменные L_* автоматически преобразовываются в соответствующий элемент языкового массива, если в коде этой переменной не присваивается (то есть не переопределяется) особое значение. Например, {L_USERNAME} преобразуется в $user->lang['USERNAME']. Шаблонные переменные LA_* обрабатываются таким же образом, но они экранируются для помещения в код JavaScript. Таким образом, уменьшится необходимость присваивать массу значений языковых переменных в модификациях.

Блоки, циклы

Основной цикл блочного уровня остается прежним и принимает следующий вид:

<!-- BEGIN loopname -->
	markup, {loopname.X_YYYYY}, etc.
<!-- END loopname -->

Подключение файлов

Есть одна вещь, которая существовала в 2.0.x, но не существует в 3.0.x, — это возможность присвоения шаблона переменной. Эта возможность использовалась (например) для вывода списка перехода на другой форум. Вместо этого (может быть, это лучше, а может быть, и нет, но это гораздо более гибкая возможность) у нас сейчас есть INCLUDE. Выглядит просто:
<!-- INCLUDE filename -->

Вы заметите, что в большинстве шаблонов 3.0 код начинается со строки <!-- INCLUDE overall_header.html --> или <!-- INCLUDE simple_header.html --> и т. д. В 2.0.x выбор того, какой заголовок использовать, определялся прямо в коде. В 3.0.x дизайнер шаблонов может сам определять то, что он хочет. Обратите внимание, что вы можете создать новые шаблоны (то есть отличные от тех, что поставляются в наборе по умолчанию), используя систему, и подключить их как вам угодно... возможно, пригодится при создании общей панели «меню» или чего-то в этом роде. Нет нужды изменять массу файлов, как это было в 2.0.x.

PHP

Спорным решением видится возможность подключать PHP прямо внутри шаблонов. Это можно сделать, заключив PHP в соответствующие теги:

<!-- PHP -->
	echo "привет!";
<!-- ENDPHP -->

Конструкции условий и управления

Наиболее важным нововведением в 3.0.x являются конструкции условий и управления: «если выполняется такое-то условие, делаем это, иначе делаем то». Внедренная система очень похожа на Smarty. Это может поначалу ввести в заблуждение некоторых людей, но такая система имеет огромный потенциал, большую гибкость, требуя лишь небольшого представления о себе. В самых простых случаях такие конструкции имеют следующий вид:

<!-- IF выражение -->
	разметка
<!-- ENDIF -->

<!-- IF loop.S_ROW_COUNT is even -->
	разметка
<!-- ENDIF -->

== [eq]
!= [neq, ne]
<> (same as !=)
!== (not equivalent in value and type)
=== (equivalent in value and type)
> [gt]
< [lt]
>= [gte]
<= [lte]
&& [and]
|| [or]
% [mod]
! [not]
+
-
*
/
,
<< (побитовый сдвиг влево)
>> (побитовый сдвиг вправо)
| (побитовое «или»)
^ (побитовое исключающее «или» — xor)
& (побитовое «и»)
~ (побитовое отрицание)
is (используется для связки операций сравнения)

even (четное)
odd (нечетное)
div (делится без остатка)

<!-- IF выражение1 -->
	разметка
<!-- ELSEIF выражение2 -->
	разметка
	.
	.
	.
<!-- ELSEIF выражениеN -->
	разметка
<!-- ELSE -->
	разметка
<!-- ENDIF -->

<table>
	<!-- IF loop.S_ROW_COUNT is even -->
		<tr class="row1">
	<!-- ELSE -->
		<tr class="row2">
	<!-- ENDIF -->
	<td>ПРИВЕТ!</td>
</tr>
</table>

<table>
	<!-- IF loop.S_ROW_COUNT > 10 -->
		<tr bgcolor="#FF0000">
	<!-- ELSEIF loop.S_ROW_COUNT > 5 -->
		<tr bgcolor="#00FF00">
	<!-- ELSEIF loop.S_ROW_COUNT > 2 -->
		<tr bgcolor="#0000FF">
	<!-- ELSE -->
		<tr bgcolor="#FF00FF">
	<!-- ENDIF -->
	<td>привет!</td>
</tr>
</table>

<!-- IF S_USER_LOGGED_IN -->
	разметка
<!-- ENDIF -->

Расширенный синтаксис для блоков и циклов

Вернемся к нашим циклам — они могут быть расширены следующими дополнениями. Во-первых, вы можете установить начальную и конечную точку цикла. Например:

<!-- BEGIN loopname(2) -->
	разметка
<!-- END loopname -->

<!-- BEGIN loop -->
	разметка
<!-- BEGINELSE -->
	разметка
<!-- END loop -->

<!-- IF .loop -->
	<!-- BEGIN loop -->
		разметка
	<!-- END loop -->
<!-- ELSE -->
	разметка
<!-- ENDIF -->

<!-- IF .loop > 2 -->
	<!-- BEGIN loop -->
		разметка
	<!-- END loop -->
<!-- ELSE -->
	разметка
<!-- ENDIF -->

<!-- BEGIN firstloop -->
	{firstloop.MY_VARIABLE_FROM_FIRSTLOOP}

	<!-- BEGIN secondloop -->
		{firstloop.secondloop.MY_VARIABLE_FROM_SECONDLOOP}
	<!-- END secondloop -->
<!-- END firstloop -->

<!-- BEGIN l_block1 -->
	<!-- IF l_block1.S_SELECTED -->
		<strong>{l_block1.L_TITLE}</strong>
		<!-- IF S_PRIVMSGS -->

			<!-- the ! at the beginning of the loop name forces the loop to be not a nested one of l_block1 -->
			<!-- BEGIN !folder -->
				<!-- IF folder.S_FIRST_ROW -->
					<ul class="nav">
				<!-- ENDIF -->

				<li><a href="/{folder.U_FOLDER}">{folder.FOLDER_NAME}</a></li>

				<!-- IF folder.S_LAST_ROW -->
					</ul>
				<!-- ENDIF -->
			<!-- END !folder -->

		<!-- ENDIF -->

		<ul class="nav">
		<!-- BEGIN l_block2 -->
			<li>
				<!-- IF l_block1.l_block2.S_SELECTED -->
					<strong>{l_block1.l_block2.L_TITLE}</strong>
				<!-- ELSE -->
					<a href="/{l_block1.l_block2.U_TITLE}">{l_block1.l_block2.L_TITLE}</a>
				<!-- ENDIF -->
			</li>
		<!-- END l_block2 -->
		</ul>
	<!-- ELSE -->
		<a class="nav" href="/{l_block1.U_TITLE}">{l_block1.L_TITLE}</a>
	<!-- ENDIF -->
<!-- END l_block1 -->

<!-- BEGIN l_block1 -->
	<!-- IF l_block1.S_SELECTED -->
		разметка
	<!-- ELSE -->
		<a class="nav" href="/{l_block1.U_TITLE}">{l_block1.L_TITLE}</a>
	<!-- ENDIF -->
<!-- END l_block1 -->

<!-- BEGIN l_block1 -->
.
.
	<!-- IF S_PRIVMSGS -->

		<!-- BEGIN !folder -->
			<!-- IF folder.S_FIRST_ROW -->
				<ul class="nav">
			<!-- ENDIF -->

			<li><a href="/{folder.U_FOLDER}">{folder.FOLDER_NAME}</a></li>

			<!-- IF folder.S_LAST_ROW -->
				</ul>
			<!-- ENDIF -->
		<!-- END !folder -->

	<!-- ENDIF -->
.
.
<!-- END l_block1 -->

<!-- BEGIN l_block1 -->
.
.
	<ul class="nav">
	<!-- BEGIN l_block2 -->
		<li>
			<!-- IF l_block1.l_block2.S_SELECTED -->
				<strong>{l_block1.l_block2.L_TITLE}</strong>
			<!-- ELSE -->
				<a href="/{l_block1.l_block2.U_TITLE}">{l_block1.l_block2.L_TITLE}</a>
			<!-- ENDIF -->
		</li>
	<!-- END l_block2 -->
	</ul>
.
.
<!-- END l_block1 -->

<!-- IF folder.S_FIRST_ROW -->
	<ul class="nav">
<!-- ENDIF -->

<li><a href="/{folder.U_FOLDER}">{folder.FOLDER_NAME}</a></li>

<!-- IF folder.S_LAST_ROW -->
	</ul>
<!-- ENDIF -->

<ul class="nav"> <!-- записывается на первой итерации -->
	<li>first element</li> <!-- записывается на первой итерации -->
	<li>second element</li> <!-- записывается на второй итерации -->
	<li>third element</li> <!-- записывается на третьей итерации -->
</ul> <!-- записывается на третьей итерации -->

<!-- IF folder.S_FIRST_ROW -->
	<ul class="nav">
<!-- ELSEIF folder.S_LAST_ROW -->
	</ul>
<!-- ELSE -->
	<li><a href="/{folder.U_FOLDER}">{folder.FOLDER_NAME}</a></li>
<!-- ENDIF -->

<ul class="nav"> <!-- записывается на первой итерации -->
	<li>second element</li> <!-- записывается на второй итерации -->
</ul> <!-- записывается на третьей итерации -->

Формы

Если форма используется для нетривиальных операций (например, нечто большее, чем форма перехода на другой форум), то она должна содержать шаблонную переменную {S_FORM_TOKEN}.

<form method="post" id="mcp" action="{U_POST_ACTION}">

	<fieldset class="submit-buttons">
		<input type="reset" value="{L_RESET}" name="reset" class="button2" /> 
		<input type="submit" name="action[add_warning]" value="{L_SUBMIT}" class="button1" />
		{S_FORM_TOKEN}
	</fieldset>
</form>

4.ii. Наследование шаблонов

Если новый шаблон основывается на существующем, то необязательно предоставлять все файлы шаблонов. Можно объявить шаблон «наследником» («inheriting») в файле конфигурации шаблона.

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

Эффект в использовании такой системы состоит в том, что механизм шаблонов будет использовать файлы нового шаблона, если они имеются, и обращаться к файлам базового шаблона в другом случае. Объявление стиля наследующим также позволяет ему использовать некоторые настройки конфигурации от базового стиля, особенно хранение в базе данных.

Мы крайне рекомендуем использовать наследование стилей, основанных на стилях их стандартного комплекта, поскольку это облегчит процесс обновления.

        # Общая информация по данному шаблону
        name = inherits
        copyright = © phpBB Group, 2007
        version = 3.0.3

        # Определение другого битового поля шаблона
        template_bitfield = lNg=

        # Наследуем?
        inherit_from = prosilver

Наверх

5. Наборы символов и кодировки

Что такое Unicode, UCS и UTF-8?

Универсальный набор символов (Universal Character Set — UCS), описанный в ISO/IEC 10646, состоит из большого числа символов. Каждый из них имеет уникальное имя и кодовый указатель, являющийся целым числом. Unicode, являющийся отраслевым стандартом, дополняет универсальный набор символов дальнейшей информацией о свойствах символов и их альтернативных кодировках. Более подробную информацию по Unicode можно найти на веб-сайте Unicode Consortium. Одна из кодировок Unicode — это 8-битный формат преобразования Unicode (Unicode Transformation Format — UTF-8). Она кодирует символы, используя до четырех байтов, нацеливаясь на совместимость с Американским стандартным кодом обмена информацией (American Standard Code for Information Interchange), являющийся 7-битной кодировкой относительно небольшого подмножества UCS.

Использование Unicode в phpBB

К сожалению, PHP до версии 6 не имеет встроенной поддержки Unicode. Большинство функций просто рассматривают строку как последовательность байтов, предполагая, что каждый символ занимает ровно один байт. Такое поведение, тем не менее, позволяет хранить закодированный при помощи UTF-8 текст в строках PHP, но многие операции со строками приведут к неожидаемым результатам. Чтобы обойти эту проблему, мы написали несколько альтернативных функций по отношению к родным строковым операциям PHP, эти функции используют кодовые указатели вместо байтов. Они расположены в файле /includes/utf/utf_tools.php. Также они рассмотрены в Документации по исходному коду phpBB3. Большое количество родных функций PHP работают с UTF-8, если соблюдать определенные ограничения. Например, explode работает верно, если первый и последний символы строки-разделителя являются ASCII-символами.

Из кодировок символов phpBB использует только ASCII и UTF-8. Точнее сказать, все символы закодированы в UTF-8, поскольку ASCII является подмножеством UTF-8. Единственное исключение из этого правила составляют участки кода, которые работают с внешними системами, использующими другие кодировки и наборы символов. Такие внешние данные должны быть преобразованы в UTF-8 при помощи функции utf8_recode(), имеющейся в phpBB. Она поддерживает множество других наборов символов и кодировок, полный список приведен ниже.

При помощи request_var() вы можете позволить либо все символы UCS в пользовательском вводе, либо ограничить ввод только ASCII-символами. Эта возможность управляется третьим параметром функции $multibyte. Вы должны включать многобайтные кодировки в сообщениях, ЛС, заголовках тем, названиях форумов и так далее. Однако, это не требуется для служебных нужд, например, для переменной $mode, которая, как бы то ни было, должна содержать только предопределенный список ASCII-строк.

// входная строка, которая должна содержать многобайтный набор символов
$_REQUEST['multibyte_string'] = 'Kase';
// печатаем запрошенную переменную как строка UTF-8, включив многобайтный набор символов
echo request_var('multibyte_string', '', true);
// печатаем запрошенную переменную как ASCII-строку
echo request_var('multibyte_string', '');

Kase
K??se

Нормализация Unicode

Если вы получаете пользовательский ввод с многобайтным набором символов, вы дополнительно должны нормализовать строки при помощи функции utf8_normalize_nfc() прежде чем работать с ними. Это необходимо для уверенности в том, что два одинаковых символа могут быть представлены в двоичном виде строго одинаково. Например, символ A может быть представлен и как U+00C5 (LATIN CAPITAL LETTER A WITH RING ABOVE), и как U+212B (ANGSTROM SIGN). phpBB использует каноническую декомпозицию с последующей канонической композицией (Normalization Form Canonical Composition, NFC) для всего текста. Итак, верный вариант вышеприведенного примера будет выглядеть так:

$_REQUEST['multibyte_string'] = 'Kase';

// нормализуем многобайтные строки
echo utf8_normalize_nfc(request_var('multibyte_string', '', true));
// ASCII-строки не нуждаются в нормализации
echo request_var('multibyte_string', '');

Приведение регистра

Теперь регистронезависимое сравнение строк невозможно при помощи strtolower или strtoupper, поскольку некоторые символы имеют несколько форм нижнего регистра или несколько форм верхнего регистра, в зависимости от их положения в слове. Функции utf8_strtolower и utf8_strtoupper испытывают такую же проблему, так что они могут использоваться только для отображения верхнерегистровой или нижнерегистровой версии строки, но они бесполезны при выполнении регистронезависимых сравнений. Итак, вместо этого вам нужно использовать приведение регистра, что даст вам регистронезависимую версию строки, так что вы сможете выполнять регистронезависимые сравнения. Нормализованная по NFC строка может быть приведена по регистру при помощи utf8_case_fold_nfc().

// Плохо — строки могут быть одинаковыми, даже если strtolower различаются

if (strtolower($string1) == strtolower($string2))
{
	echo '$string1 и $string2 равны либо различны по регистру';
}

if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2))
{
	echo '$string1 и $string2 равны либо различны по регистру';
}

Распознавание схожих имен

phpBB предлагает специальный метод utf8_clean_string, который используется для проверки того, что идентификаторы строк уникальны. Этот метод использует совместную декомпозицию с последующей канонической композицией (Normalization Form Compatibility Composition, NFKC) вместо NFC и заменяет символы, выглядящие схожим образом, на особый экземпляр из класса эквивалентов. Этот метод на данный момент используется для имен пользователей и названий групп, чтобы избежать путаницу в том случае, если имена и названия выглядят схожим образом.

Наверх

6. Правила перевода (интернационализация, локализация)

6.i. Стандартизация

Причина:

phpBB — один из наиболее широко переведенных проектов с открытым исходным кодом, текущая стабильная версия доступна в более чем 60 локализациях. Пока специальный подход к наименованию языковых пакетов работает, для phpBB3 и далее мы надеемся сделать этот процесс более разумным, что позволит улучшить взаимодействие текущих и будущих веб-обозревателей.

Кодировка:

В phpBB3 кодировкой для результата выполнения программы является UTF-8, универсальная кодировка символов, созданная Unicode Consortium, которая является надможеством US-ASCII и ISO-8859-1. Использование одного набора символов, который одновременно поддерживает все скрипты, в прошлом бы потребовавшие различные кодировки (например: с ISO-8859-1 по ISO-8859-15 (латинский, греческий, кириллический, тайский, иврит, арабский); GB2312 (упрощенный китайский); Big5 (традиционный китайский), EUC-JP (японский), EUC-KR (корейский), VISCII (вьетнамский); и так далее), избавляет от необходимости преобразовывать текст между разными кодировками, а также улучшает доступность многоязычных форумов.

Смысл в том, что языковые файлы phpBB теперь должны быть сохранены в кодировке UTF-8, а также они не должны содержать BOM из соображений совместимости с версиями PHP без поддержки Unicode. Для них на форумах используется латинский набор символов (то есть большинство европейских языков), данное изменение будет прозрачным, поскольку UTF-8 является надможеством US-ASCII и ISO-8859-1.

Метка языка:

Комитет IETF недавно опубликовал RFC 4646 для меток, идентифицирующих языки; этот документ, в сочетании с RFC 4647, вытесняет устаревший RFC 3006 и еще более старый RFC 1766. RFC 4646 использует ISO 639-1/ISO 639-2, ISO 3166-1 alpha-2, ISO 15924 и UN M.49 для определения меток языков. Каждая метка составлена из подметок, которые не являются регистрозависимыми, а также могут быть пустыми.

Порядок следования подметок, в случае если ни одна из них не пуста, следующий: язык-письмо-регион-разновидность-расширение-частное применение. Если какая-то подметка пустая, соответствующий дефис также опускается. Таким образом, языковая метка для английского языка будет en, а не en-----.

Большинство языковых меток состоит из двух- или трехбуквенных языковых подметок (согласно ISO 639-1/ISO 639-2). Иногда следом идет двухбуквенная или трехзначная цифровая метка региона (согласно ISO 3166-1 alpha-2 или UN M.49). Вот некоторые примеры:

Основная цель языковых меток — это сообщить необходимую полезную отличительную информацию, в то же время используя как можно более короткие имена. Например, использование en, fr и ja в отличие от en-GB, fr-FR и ja-JP, поскольку мы знаем, что английский, французский и японский языки — родные для Великобритании, Франции и Японии соответственно.

Далее рассмотрим код письма языка согласно ISO 15924, когда его следует использовать, а когда — нет. Например, в то время как en-Latn синтаксически верно для описания англоязычного текста, написанного латинским письмом, на самом деле написание слов на английском языке выполняется более или менее исключительно на английской письменности. Для таких языков, как английский, использующих в своей записи единственный вид письма, реестр языковых подметок IANA содержит поле «Без письма», означающее, что код письма должен опускаться, если особая языковая метка не требует особый код письма. Некоторые языки используют более одного вида письменности, и в таких случаях код письма рекомендуется, поскольку конечный пользователь может читать свой язык на одной системе письма, но не может на другой. Приведем несколько примеров:

Использование трехзначного цифрового кода UN M.49 вместо двухбуквенного ISO 3166-1 alpha-2 применимо в случае, если требуется макрогеографический объект и/или ISO 3166-1 alpha-2 неоднозначно.

Примеры указания английского языка с макрогеографическим регионом:

Примеры указания испанского языка с макрогеографическим регионом:

Примеры мест, где ISO 3166-1 alpha-2 неоднозначно и потому UN M.49 предпочтительнее:

Макроязыки и наддиалекты:

В RFC 4646 предвидятся возможности, которые должны появиться в ISO 639-3 (пока это проект), где будет предоставлено наиболее полное перечисление всех языков, включая живые, мертвые, древние и искусственные языки, как хорошо распространенные, так и редкие, и бесписьменные. Новая особенность документа ISO 639-3, в сравнении с двумя предыдущими редакциями, — это концепция макроязыков, примерами которых служат арабский и китайский языки. В таких случаях их соответствующие коды: ar и zh — очень неясны в плане используемого диалекта/наддиалекта или, возможно, более краткого классического варианта, который может быть различным для всех пользователей, кроме очень образованных. Для таких макроязыков рекомендуется использование метки подъязыка в качестве суффикса к метке макроязыка, например:

6.ii. Другие положения

Нормализация языковых меток для phpBB:

Для phpBB языковые метки не используются в их сырой форме, вместо этого они преобразуются к нижнему регистру, затем дефисы -заменяются на знаки подчеркивания _, где необходимо. Несколько примеров:

Как использовать iso.txt:

iso.txt — это небольшой текстовый файл в кодировке UTF-8, состоящий из трех строк:

1. Английское наименование языка
2. Местное название языка
3. Информация об авторах

iso.txt автоматически создается системой отправки языковых пакетов на phpBB.com. Вам не нужно создавать этот файл самим, если вы планируете публиковать свой языковой пакет на phpBB.com, но имейте в виду, что phpBB сам по себе требует наличия этого файла.

Вследствие того что метки языков сами по себе подразумевают их чтение машиной, они могут быть непонятны и запутаны для человека, поэтому требуется содержательное описание в iso.txt. В то время как обозначение en-US довольно легко понимается как «Английский язык, употребляемый в Соединенных Штатах», de-CH уже более сложно, соответственно, меньше людей знают, что de обозначает «Deutch», немецкое слово «Немецкий», и CH является аббревиатурой официального латинского названия Швейцарии «Confoederatio Helvetica».

При описании на английском языке английское наименование всегда идет первым, а все дополнительные атрибуты, необходимые для описания подметок внутри кода языка, следуют далее, разделенные запятыми и заключенные в круглые скобки, например:

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

Рассмотрение двунаправленного Unicode:

Поскольку phpBB теперь использует UTF-8, все переводчики должны принять во внимание, что определенные строки могут отрображаться, когда направление письма в документе или противоположно обычному, или неопределено.

Различные управляющие символы Unicode для двунаправленного текста и их HTML-эквивалетны следующие:

Для файла iso.txt направление текста может быть явно задано при помощи специальных символов Unicode, используя любой из трех способов: символы Left-to-Right/Right-to-Left Mark/Embedding/Override — без них порядок следования символов может быть неверен, и т. д.:

При выборе того, какой из трех способов использовать, в большинстве случаев достаточно поместить «сильные» символы LRM или RLM, чтобы полностью заключить в себе неоднозначный символ пунктуации и, таким образом, заставить наследовать верное направление письма.

В некоторых случаях могут быть смешанные виды письма (слева направо и справа налево), так что использование LRE и RLE совместно с PDF может быть уместно. Наконец, в очень редких случаях, где направление должно быть выставлено принудительно, используйте LRO и RLO вместе с PDF.

За дальнейшей информацией по техническим приемам авторинга двунаправленного текста обращайтесь к руководству W3C по техническим приемам для XHTML-страниц с двунаправленным текстом.

Работа с заполнителями:

Поскольку phpBB переводится на языки с различными правилами порядка следования слов, в отличие от английского, то рассмотрим особые значения, которые могут встречаться. Возьмем для примера чрезвычайно простую строку «Страница X из Y», которая на английском языке может быть закодирована следующим образом:

	...
'PAGE_OF'	=>	'Page %s of %s',
		/* Просто делаем замену так, как она
		следует в тексте с надеждой, что порядок будет верным */
	...

	...
'PAGE_OF'	=>	'Page %1$s of %2$s',
		/* Явное указание порядка замены,
		даже если на английском порядок был бы таким же */
	...

	...
'PAGE_OF'	=>	'Total of %2$s pages, currently on page %1$s',
		/* Явное указание порядка замены,
		но для английского языка получилось все наоборот,
		так как общее количество стоит на первом месте */
	...

6.iii. Стиль написания

Разные советы:

Поскольку языковые файлы — это PHP-файлы, в которых разные строки для phpBB хранятся внутри массива и которые по очереди используются для отображения на HTML-странице, правила синтаксиса для обоих типов должны соблюдаться. Потенциально проблематичные символы: ' (одиночная прямая кавычка/апостроф), " (двойная прямая кавычка), < (знак «меньше»), > (знак «больше») и & (амперсанд).

// Неверно — Неэкранированный символ одиночной прямой кавычки (апострофа) вызовет ошибку синтаксического анализа PHP

	...
'CONV_ERROR_NO_AVATAR_PATH'
	=>	'Замечание для разработчика: вы должны указать $convertor['avatar_path'] для использования %s.',
	...

	...
'CONV_ERROR_NO_AVATAR_PATH'
	=>	'Замечание для разработчика: вы должны указать $convertor[\'avatar_path\'] для использования %s.',
	...

	...
'USE_PERMISSIONS'	=>	'Test out user's permissions',
	...

	...
'USE_PERMISSIONS'	=>	'Test out user\'s permissions',
	...

	...
'USE_PERMISSIONS'	=>	'Test out user’s permissions',
	...

	...
'FOO_BAR'	=>	'PHP version < 4.3.3.<br />
	Visit "Downloads" at <a href="http://www.php.net/">www.php.net</a>.',
	...

	...
'FOO_BAR'	=>	'PHP version &lt; 4.3.3.<br />
	Visit &quot;Downloads&quot; at <a href="http://www.php.net/">www.php.net</a>.',
	...

	...
'FOO_BAR'	=>	'PHP version &lt; 4.3.3.<br />
	Visit “Downloads” at <a href="http://www.php.net/">www.php.net</a>.',
	...

	...
'FOO_BAR'	=>	'<a href="http://somedomain.tld/?foo=1&bar=2">Foo & Bar</a>.',
	...

	...
'FOO_BAR'	=>	'<a href="http://somedomain.tld/?foo=1&amp;bar=2">Foo &amp; Bar</a>.',
	...

Орфография, пунктуация, грамматика и так далее:

Языковой пакет по умолчанию, представленный в комлекте phpBB, — это британский английский с орфографией «Кембридж юниверсити пресс (Cambridge University Press)» и имеющий языковой код en. Стиль и характер написания устремлен к официальному, и переводчики должны подражать этому стилю, по крайней мере, в вопросе по использованию максимально короткого языкового кода. Менее официальные переводы или переводы с разговорными выражениями должны обозначаться таковыми либо через метку расширение, либо через метку частное использование внутри кода языка.

Наверх

7. История версий данного руководства

Редакция 8732

Добавлена информация о файлах конфигурации.
Добавлено наследование шаблонов.

Редакция 8596+

Удалены выражения sql_build_array('MULTI_INSERT'....
Добавлено объяснение sql_multi_insert().

Редакция 1.31

Добавлено: add_form_key и check_form_key.

Редакция 1.24

Добавлена глава 5. Наборы символов и кодировки, чтобы объяснить рекомендуемые способы работы со строками в phpBB.

Редакция 1.16

Добавлена глава 6. Правила перевода (интернационализация, локализация), чтобы объяснить принятый формат и соображения авторинга языковых пакетов, создаваемых для phpBB.

Редакция 1.11-1.15

Различные поправки в форматировании документа, орфографии, пунктуации и грамматике.

Редакция 1.9-1.10

Добавлено sql_query_limit в 2.iii. Оформление SQL.

Редакция 1.8

Некоторые поправки в формулировках
Обновлен параграф 1.iii. Расположение файлов для отражения недавних изменений
Расширен параграф 2.ii. Оформление кода.
Добавлено объяснение sql_in_set и sql_build_query в 2.iii. Оформление SQL.
Обновлена глава 3. Работа со стилями.
Обновлена глава 4. Работа с шаблонами, чтобы объяснить проверку циклов, прерывание циклов и прочие изменения, которые мы недавно проделали.

Редакция 1.5

Изменен параграф «Использование общих функций» в 2.v. Общие рекомендации

Наверх

8. Авторское право и отказ от ответственности

Данное приложение является программным продуктом с открытым исходным кодом, выпускаемым в соответствии с лицензией GPL. См. исходный код и директорию docs для получения более подробной информации. Авторское право на данный программный пакет и его содержимое: (c) 2000, 2002, 2005, 2007 phpBB Group, все права защищены.

Перевод документа выполнен командой официальной русской поддержки phpBB.

Наверх

$Id: coding-guidelines.html 9036 2008-10-25 14:16:17Z acydburn $