Руководство PHP стиля 

Эта страница описывает стили кодирования которых придерживались при разработке CodeIgniter. Мы не требуем использовать эти стили в своих приложениях CodeIgniter, хотя они рекомендуются.

Формат файла

Файл должен быть сохранен в кодировке Unicode (UTF-8). BOM использовать НЕ следует. В отличии от UTF-16 и UTF-32, нет порядка обозначения байтов в файле с UTF-8 кодировкой, и BOM может иметь отрицательный эффект в PHP при отправе выхода, предотвращая возможность установки собственных заголовков. Следует использовать Unix окончания строк (LF).

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

TextMate

  1. Откройте настройки приложения (Application Preferences)
  2. Нажмите кнопку дополнительно (Advanced), а затем вкладку “Сохранить” (“Save”)
  3. В “Кодировка файла” (“File Encoding”), выберите “UTF-8 (рекомендуется)” (“UTF-8 (recommended)”)
  4. В “Окончания строк” (“Line Endings”), выберите “LF (рекомендуется)” (“LF (recommended)”)
  5. Опционально: отметьте “Использовать для существующих файлов” если вы хотите изменять окончания строк в открытых файлах для новых предпочтений.

BBEdit

  1. Откройте настройки приложения (Application Preferences)
  2. Выберите “Кодировки текста” (“Text Encodings”) слева.
  3. В “Кодировка для новых документов по умолчанию” (“Default text encoding for new documents”), выберите “Unicode (UTF-8, без BOM)” (“Unicode (UTF-8, no BOM)”)
  4. Опционально: В “Если кодировка файла не может быть определена, использовать “Unicode (UTF-8, без BOM)”
  5. Выберите “Текстовые файлы” (“Text Files”) слева.
  6. В “Разрывы строк по умолчанию” (“Default line breaks”), выберите “Mac OS X и Unix (LF)”

Закрывающий PHP тэг

Закрывающий PHP тэг в документе ?> опциональный для PHP парсера. Однако, если есть пробел после закрывающего тега, будет ли он введен разработчиком, рользователем или FTP приложением, могут возникнуть нежелательные выход (output), PHP ошибки или если последние подавляются, пустые страницы. По этой причине, все PHP файлы ДОЛЖНЫ ИСКЛЮЧИТЬ закрывающий PHP тэг и заканчиваться одной пустой строкой вместо него.

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

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

НЕПРАВИЛЬНО:

somelibrary.php
someLibrary.php
SOMELIBRARY.php
Some_Library.php

Application_config.php
Application_Config.php
applicationConfig.php

ПРАВИЛЬНО:

Somelibrary.php
Some_library.php

applicationconfig.php
application_config.php

Кроме того, именя файла класса должно совпадать с именем самого класса. Например, если у вас есть Класс с именем Myclass, то имя файла класса должно быть Myclass.php.

Именования методов и классов

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

НЕПРАВИЛЬНО:

class superclass
class SuperClass

ПРАВИЛЬНО:

class Super_class
class Super_class {

        public function __construct()
        {

        }
}

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

НЕПРАВИЛЬНО:

function fileproperties()               // not descriptive and needs underscore separator
function fileProperties()               // not descriptive and uses CamelCase
function getfileproperties()            // Better!  But still missing underscore separator
function getFileProperties()            // uses CamelCase
function get_the_file_properties_from_the_file()        // wordy

ПРАВИЛЬНО:

function get_file_properties()  // descriptive, underscore separator, and all lowercase letters

Имена переменных

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

НЕПРАВИЛЬНО:

$j = 'foo';             // single letter variables should only be used in for() loops
$Str                    // contains uppercase letters
$bufferedText           // uses CamelCasing, and could be shortened without losing semantic meaning
$groupid                // multiple words, needs underscore separator
$name_of_last_city_used // too long

ПРАВИЛЬНО:

for ($j = 0; $j < 10; $j++)
$str
$buffer
$group_id
$last_city

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

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

DocBlock комментарии в стиле классов, методов и декларации, которые могут быть подхвачены средой разработки (IDE):

/**
 * Super Class
 *
 * @package     Package Name
 * @subpackage  Subpackage
 * @category    Category
 * @author      Author Name
 * @link        http://example.com
 */
class Super_class {
/**
 * Encodes string for use in XML
 *
 * @param       string  $str    Input string
 * @return      string
 */
function xml_encode($str)
/**
 * Data for class manipulation
 *
 * @var array
 */
public $data = array();

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

// break up the string by newlines
$parts = explode("\n", $str);

// A longer comment that needs to give greater detail on what is
// occurring and why can use multiple single-line comments.  Try to
// keep the width reasonable, around 70 characters is the easiest to
// read.  Don't hesitate to link to permanent external resources
// that may provide greater detail:
//
// http://example.com/information_about_something/in_particular/

$parts = $this->foo($parts);

Постоянные

Постоянные используют руководящие принципы схожие на принципы переменнх, за исключением того, что они должны быть в ВЕРХНЕМ регистре. Всегда используйте постоянные CodeIgniter соответствующие SLASH, LD, RD, PATH_CACHE и т.д.

НЕПРАВИЛЬНО:

myConstant      // missing underscore separator and not fully uppercase
N               // no single-letter constants
S_C_VER         // not descriptive
$str = str_replace('{foo}', 'bar', $str);       // should use LD and RD constants

ПРАВИЛЬНО:

MY_CONSTANT
NEWLINE
SUPER_CLASS_VERSION
$str = str_replace(LD.'foo'.RD, 'bar', $str);

TRUE, FALSE и NULL

Ключевые слова TRUE, FALSE и NULL всегда должны быть в верхнем регистре.

НЕПРАВИЛЬНО:

if ($foo == true)
$bar = false;
function foo($bar = null)

ПРАВИЛЬНО:

if ($foo == TRUE)
$bar = FALSE;
function foo($bar = NULL)

Логические операторы

Использование || “OR” оператор сравнения обескураживает, так как его ясность на некоторых выходных устройствах является низкой (очень схож с числом 11, для сравнения). && предпочтительнее AND но в любом случае приемлемы, и пробел должен всегда предшествовать ! и следовать после него.

НЕПРАВИЛЬНО:

if ($foo || $bar)
if ($foo AND $bar)  // okay but not recommended for common syntax highlighting applications
if (!$foo)
if (! is_array($foo))

ПРАВИЛЬНО:

if ($foo OR $bar)
if ($foo && $bar) // recommended
if ( ! $foo)
if ( ! is_array($foo))

Сравнение возвращаемого значения и приведение типов

Некоторые PHP функции возвращают FALSE в случае неудачи, но могут также возвращать значения “” или 0, которые будут возвращать FALSE в свободных сравнениях. Явно сравнивая тип переменной при использовании этих возвращаемых значений в условных операторах, гарантируют возвращаемое значение - это действительно то, что вы ожидаете, а не значение, которое имеет эквивалент свободного типа оценки.

Используйте обязательные требования в возвращаемом типе и проверяйте свои собственные переменные. Используйте === и !== при необходимости.

НЕПРАВИЛЬНО:

// If 'foo' is at the beginning of the string, strpos will return a 0,
// resulting in this conditional evaluating as TRUE
if (strpos($str, 'foo') == FALSE)

ПРАВИЛЬНО:

if (strpos($str, 'foo') === FALSE)

НЕПРАВИЛЬНО:

function build_string($str = "")
{
        if ($str == "") // uh-oh!  What if FALSE or the integer 0 is passed as an argument?
        {

        }
}

ПРАВИЛЬНО:

function build_string($str = "")
{
        if ($str === "")
        {

        }
}

Смотрите также информацию о типажах, которые могут быть вполне полезны. Приведение типов имеет несколько иной эффект нежели желаемый. При приведении переменной в виде строки, например, NULL и булево FALSE переменные становятся пустыми строками, 0 (и другие числа) становятся строкой или числом, а булево TRUE становится “1”:

$str = (string) $str; // cast $str as a string

Отладка кода

Не оставляйте отладочного кода в материалах даже в закомментированном виде. Такие вещи как var_dump(), print_r(), die()/exit() не следует включать в ваш код, если они не несут отладочного смысла.

Пробелы в файлах

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

Совместимость

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

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

Один файл для класса

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

Пробелы

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

Разрывы строк

Файлы должны быть сохранены с Unix разрывами строк. Это больше вопрос для разработчиков, которые работают в Windows, но в любом случае убедитесь, что ваш текстовый редактор настроен для сохранения файлов с Unix разрывами строк.

Отступы кода

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

НЕПРАВИЛЬНО:

function foo($bar) {
        // ...
}

foreach ($arr as $key => $val) {
        // ...
}

if ($foo == $bar) {
        // ...
} else {
        // ...
}

for ($i = 0; $i < 10; $i++)
        {
        for ($j = 0; $j < 10; $j++)
                {
                // ...
                }
        }

try {
        // ...
}
catch() {
        // ...
}

ПРАВИЛЬНО:

function foo($bar)
{
        // ...
}

foreach ($arr as $key => $val)
{
        // ...
}

if ($foo == $bar)
{
        // ...
}
else
{
        // ...
}

for ($i = 0; $i < 10; $i++)
{
        for ($j = 0; $j < 10; $j++)
        {
                // ...
        }
}

try
{
        // ...
}
catch()
{
        // ...
}

Скобки и пробелы

В основном, скобки не должны использовать дополнительных пространств. Исключение состоит в том, что пространство должно всегда следовать управляющей структуре PHP которая содержится в скобках (объявление, do-while, elseif, for, foreach, if, switch, while), чтобы помочь отличить их от функций и повысить читаемость текста.

НЕПРАВИЛЬНО:

$arr[ $foo ] = 'foo';

ПРАВИЛЬНО:

$arr[$foo] = 'foo'; // no spaces around array keys

НЕПРАВИЛЬНО:

function foo ( $bar )
{

}

ПРАВИЛЬНО:

function foo($bar) // no spaces around parenthesis in function declarations
{

}

НЕПРАВИЛЬНО:

foreach( $query->result() as $row )

ПРАВИЛЬНО:

foreach ($query->result() as $row) // single space following PHP control structures, but not in interior parenthesis

Локализованный текст

Библиотеки CodeIgniterдолжны использовать соответствующие языковые файлы, когда это возможно.

НЕПРАВИЛЬНО:

return "Invalid Selection";

ПРАВИЛЬНО:

return $this->lang->line('invalid_selection');

Приватные методы и переменные

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

public function convert_text()
private function _convert_text()

PHP ошибки

Код должен выполняться без ошибок и не полагаться на предупреждения, уведомления должны быть скрыты, чтобы соответствовать этому требованию. Например, никогда не получайте доступ к переменной, которую вы не ставили себе (ключи массива $_POST) без проверки, чтобы увидеть что она isset() (задана).

Убедитесь, что ваша среда разработки имеет журнал отчетов об ошибках доступный для всех пользователей и что display_errors (отображение ошибок) доступно в среде PHP. Вы можете проверить этот параметр:

if (ini_get('display_errors') == 1)
{
        exit "Enabled";
}

На некоторых серверах, где display_errors отключен, и у вас нет возможности изменить это в php.ini, вы также можете включить его так:

ini_set('display_errors', 1);

Примечание

Устанавливая display_errors используя ini_set() во время исполнения, отличается от доступности в PHP среде. А именно, не будет иметь никакого эффекта, если в скрипте есть фатальные ошибки.

Короткий открывающий тэг

Всегда используйте полный открывающий тэг PHP в случае, если на сервере не активирован short_open_tag.

НЕПРАВИЛЬНО:

<? echo $foo; ?>

<?=$foo?>

ПРАВИЛЬНО:

<?php echo $foo; ?>

Примечание

PHP 5.4 всегда будет иметь <?= тэг доступным.

Один оператор на строку

Никогда не объединяйте операторы в одну строку.

НЕПРАВИЛЬНО:

$foo = 'this'; $bar = 'that'; $bat = str_replace($foo, $bar, $bag);

ПРАВИЛЬНО:

$foo = 'this';
$bar = 'that';
$bat = str_replace($foo, $bar, $bag);

Строки

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

НЕПРАВИЛЬНО:

"My String"                                     // нет переменной, по этому не используйте двойные кавычки
"My string $foo"                                // необходимы фигурные скобки
'SELECT foo FROM bar WHERE baz = \'bag\''       // уродливо

ПРАВИЛЬНО:

'My String'
"My string {$foo}"
"SELECT foo FROM bar WHERE baz = 'bag'"

SQL запросы

Ключевый слова SQL всегда заглавными: SELECT, INSERT, UPDATE, WHERE, AS, JOIN, ON, IN, и.так далее.

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

НЕПРАВИЛЬНО:

// Ключевый слова в нижнем регистре и запрос очень длинный для
// одной строки (... обозначает продолжение линии)
$query = $this->db->query("select foo, bar, baz, foofoo, foobar as raboof, foobaz from exp_pre_email_addresses
...where foo != 'oof' and baz != 'zab' order by foobaz limit 5, 100");

ПРАВИЛЬНО:

$query = $this->db->query("SELECT foo, bar, baz, foofoo, foobar AS raboof, foobaz
                                FROM exp_pre_email_addresses
                                WHERE foo != 'oof'
                                AND baz != 'zab'
                                ORDER BY foobaz
                                LIMIT 5, 100");

Аргументы функции по умолчанию

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

function foo($bar = '', $baz = FALSE)