Основной стандарт кодирования (PSR-1)
Этот раздел включает в себя все то, что следует считать стандартом кодирования, необходимым для обеспечения высокого уровня технического взаимодействие между общим кодом на PHP.
Ключевые слова «ДОЛЖЕН», «НЕ ДОЛЖЕН», «ТРЕБУЕТСЯ», «СЛЕДУЕТ», "НЕ ДОЛЖЕН", "РЕКОМЕНДУЕТСЯ", "МОЖЕТ" и "ДОПОЛНИТЕЛЬНО" в этом документе должны быть интерпретированы, как описано в RFC 2119.
1. Обзор
-
Файлы ДОЛЖНЫ использовать только теги
<?php
и<?=
. -
Файлы ДОЛЖНЫ использовать только UTF-8 без BOM для PHP-кода.
-
Файлы ДОЛЖНЫ либо объявлять символы (классы, функции, константы и т.д.) либо приводить к побочным эффектам (например, генерация выходных данных, изменение настроек .ini и т. д.) но НЕ ДОЛЖНЫ делать и то, и другое.
-
Пространства имен и классы ДОЛЖНЫ следовать стандартам автозагрузки PSR-4.
-
Имена классов ДОЛЖНЫ быть объявлены в
StudlyCaps
(каждое слово в названии начинается с большой буквы). -
Константы класса ДОЛЖНЫ быть объявлены в верхнем регистре с разделителями подчеркивания.
-
Имена методов ДОЛЖНЫ быть объявлены в
camelCase
.
2. Файлы
2.1. PHP теги
Код PHP ДОЛЖЕН использовать длинные теги <?php ?>
или короткие теги <?= ?>
;
Других варинтов тегов быть НЕ ДОЛЖНО.
2.2. Кодировка символов
Код PHP ДОЛЖЕН использовать только UTF-8 без BOM.
2.3. Побочные эффекты
В файлах СЛЕДУЕТ либо объявлять структуры (классы, функции, константы и т.п.) и не создавать побочных эффектов (например: передавать данные в выходной поток, модифицировать настройки и т.п.), либо реализовывать логику, порождающую побочные эффекты, но НЕ СЛЕДУЕТ делать одновременно и то, и другое.
Под «побочными эффектами» понимается реализация логики, не связанной с объявлением классов, функций, констант и т.п. – даже подключение внешнего файла уже является «побочным эффектом».
«Побочные эффекты» включают (но не ограничиваются этим перечнем): передачу данных в выходной поток, явное использование require или include, изменение настроек, генерирование ошибочных ситуаций или порождение исключений, изменение глобальных или локальных переменных, чтение из файла или запись в файл и т.п.
Ниже приведен пример файла с объявлениями и побочными эффектами. т. е. пример того, чего следует избегать:
<?php
// побочный эффект: изменение настроек .ini
ini_set('error_reporting', E_ALL);
// побочный эффект: подключение файла
include "file.php";
// побочный эффект: генерирует вывод
echo "<html>\n";
// объявление
function foo()
{
// тело функции
}
В следующем примере показан файл, содержащий объявления без побочных эффектов т. е. пример того, как следует делать:
<?php
// объявление
function foo()
{
// тело функции
}
// условное объявление -- это НЕ побочный эффект
if (! function_exists('bar')) {
function bar()
{
// тело функции
}
}
3. Пространство имен и имена классов
Имена пространств имён и имена классов ДОЛЖНЫ следовать стандарту автозагрузки PSR-4.
В конечном итоге это означает, что каждый класс должен располагаться в отдельном файле и в пространстве имён с хотя бы одним верхним уровнем (именем производителя).
Имена классов ДОЛЖНЫ быть объявлены в StudlyCaps
.
Код, написанный для PHP 5.3 и позже, ДОЛЖЕН использовать формальные пространства имен.
Для примера:
<?php
// PHP 5.3 и позже:
namespace Vendor\Model;
class Foo
{
}
Код, написанный для 5.2.x и ранее, ДОЛЖЕН использовать соглашение о псевдопространстве имен.
Префикс Vendor_
в именах классов.
<?php
// PHP 5.2.x и ранее:
class Vendor_Model_Foo
{
}
4. Константы, свойства и методы класса
Термин «класс» относится ко всем классам, интерфейсам и трейтам.
4.1. Константы
Константы класса ДОЛЖНЫ быть объявлены в верхнем регистре с разделителями подчеркивания. Для примера:
<?php
namespace Vendor\Model;
class Foo
{
const VERSION = '1.0';
const DATE_APPROVED = '2012-06-01';
}
4.2. Свойства
Это руководство намеренно избегает каких-либо рекомендаций относительно использования
Имена свойств $StudlyCaps
, $camelCase
или $under_score
.
Какое бы соглашение об именах ни использовалось, СЛЕДУЕТ применять последовательно в разумный пределах. Это соглашение может быть на уровне поставщика, на уровне пакета, на уровне класса, или на уровне метода.
4.3. Методы
Имена методов ДОЛЖНЫ быть объявлены в camelCase()
.