Руководство по стилю PHP

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

Содержание

Руководство по стилю PHP

Формат файла

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

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

TextMate

Откройте настройки приложения.
Нажмите «Дополнительно», а затем вкладку «Сохранение».
В «Кодировка файла» выберите «UTF-8 (рекомендуется)».
В «Конечные символы» выберите «LF (рекомендуется)».
Необязательно: Установите флажок «Использовать также для существующих файлов», если вы хотите изменить конечные символы файлов, которые вы открываете, на ваш новый вариант.

BBEdit

Откройте настройки приложения.
Выберите «Кодировки текста» слева.
В «Кодировка текста по умолчанию для новых документов» выберите «Unicode (UTF-8, без BOM)».
Необязательно: В «Если кодировка файла не может быть определена, использовать» выберите «Unicode (UTF-8, без BOM)».
Выберите «Текстовые файлы» слева.
В «Конечные символы по умолчанию» выберите «Mac OS X и Unix (LF)».

Закрывающая метка PHP

Закрывающая метка PHP в документе PHP ?> необязательна для парсера PHP. Однако, если она используется, любые пробелы после закрывающей метки, внесенные разработчиком, пользователем или приложением FTP, могут привести к нежелательному выводу, ошибкам PHP или, если последние подавлены, пустым страницам. По этой причине все файлы PHP должны опустить закрывающую метку PHP и заканчиваться одной пустой строкой вместо этого.

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

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

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

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.

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

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

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

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 перед объявлением классов, методов и свойств, чтобы их могли использовать среды разработки:

/**
 * 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)

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

Использование оператора сравнения || «или» не рекомендуется, так как его наглядность на некоторых устройствах отображения низкая (например, похож на число 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 и boolean FALSE становятся пустыми строками, 0 (и другие числа) становятся строками цифр, а boolean TRUE становится “1”:

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

Отладка кода

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

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

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

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

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

Кроме того, не используйте функции 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, принимающих аргументы в скобках (declare, 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);

Строки

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

НЕВЕРНО:

"My String"                                     // no variable parsing, so no use for double quotes
"My string $foo"                                // needs braces
'SELECT foo FROM bar WHERE baz = \'bag\''       // ugly

ВЕРНО:

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

SQL-запросы

Ключевые слова SQL всегда пишутся с большой буквы: SELECT, INSERT, UPDATE, WHERE, AS, JOIN, ON, IN и т.д.

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

НЕВЕРНО:

// keywords are lowercase and query is too long for
// a single line (... indicates continuation of line)
$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)

© 2014–2020 British Columbia Institute of Technology
Licensed under the MIT License.
https://codeigniter.com/userguide3/general/styleguide.html