PSR-1. Основной стандарт написания кода.

Данная статья, это авторский перевод, описания стандарта. С оригиналом описания Вы можете ознакомиться здесь.

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

Встречающиеся ключевые слова «ДОЛЖЕН», «НЕ ДОЛЖЕН», «ТРЕБУЕТСЯ», «СЛЕДУЕТ», «НЕ СЛЕДУЕТ», «РЕКОМЕНДУЕТСЯ», «МОЖЕТ» и «ОПЦИОНАЛЬНО» в данном стандарте интерпретируются как описано в документе RFC 2119.

1. Общий обзор.

  • Файлы ДОЛЖНЫ использовать только теги вида  <?php и  <?= .
  • При использовании  PHP кода файлы ДОЛЖНЫ использовать только UTF-8 без BOM.
  • Файлам СЛЕДУЕТ либо объявлять логические части кода (классы, функции, константы и т.д.) либо вызывать побочные эффекты (например, генерировать выходные данные, изменять .ini настройки и т.д.) но НЕ СЛЕДУЕТ выполнять обе эти функции одновременно.
  • Пространства имен и классы ДОЛЖНЫ следовать стандартам автозагрузки PSR: [PSR-0, PSR-4].
  • Имена классов ДОЛЖНЫ быть объявлены в  StudlyCaps стиле.
  • Константы классов ДОЛЖНЫ быть объявлены с помощью всех заглавных букв, с использованием символа нижнего подчеркивания _ в качестве разделителя .
  • Имена методов классов ДОЛЖНЫ быть объявлены в  camelCase стиле.

2. Файлы.

2.1. PHP теги.

PHP код ДОЛЖЕН использовать только длинные теги  <?php  ?> или только короткие теги для вывода  <?=  ?> . Другие варианты тегов в PHP коде использоваться НЕ ДОЛЖНЫ.

2.2. Кодировка символов.

PHP код ДОЛЖЕН использовать только UTF-8 без BOM.

2.3. Побочные эффекты.

Содержимому файла СЛЕДУЕТ объявлять новые фрагменты кода (классы, функции, константы и т.д.) и не вызывать никаких побочных эффектов, или в других случаях файлам СЛЕДУЕТ выполнять логику с побочными эффектами, но НЕ СЛЕДУЕТ выполнять и то и другое одновременно.

Понятие «побочные эффекты» означает выполнение логики не связанной напрямую с объявлением классов, функций, констант и т.д., просто от включения файла.

«Побочные эффекты» включают (но не ограничиваются только ими): вывод данных, явное использование  require или  include, подключение к внешним сервисам, модификацию .ini настроек, выбрасывание ошибок или исключений, модификацию глобальных или статических переменных, чтение из файла или запись в файл, и т.д.

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?php
// создание "побочного эффекта": изменение ini настроек
ini_set('error_reporting', E_ALL);

// создание "побочного эффекта": загрузка файла
include "file.php"

// создание "побочного эффекта": вывод результата
echo "<html>\n";

// объявление функции
function foo()
{
    // тело функции
}

Следующий пример файла, содержит только объявления функций без создания других «побочных эффектов», и такому примеру рекомендуется следовать:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<?php
// объявление функции
function foo()
{
    // тело функции
}

// условное объявление ф-ции - НЕ является побочным эффектом
if (! function_exist('bar')) {
    function bar()
    {
        // тело функции
    }
}

3. Пространства имен и имена классов.

Пространства имен и классы ДОЛЖНЫ следовать стандартам автозагрузки PSR: [PSR-0, PSR-4].

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

Имена классов ДОЛЖНЫ быть объявлены в  StudlyCaps стиле.

Код, написанный на PHP 5.3 и выше версий ДОЛЖЕН использовать формальное пространство имен.

Для примера:

1
2
3
4
5
6
7
<?php
// PHP версии 5.3 и выше
namespace Vendor\Model;

class Foo
{
}

В коде, написанном на PHP 5.2.X и более ранних версиях СЛЕДУЕТ использовать соглашение псевдо-пространства имен, применяя для этого  Vendor_ префикс производителя в имени класса.

1
2
3
4
5
<?php
// PHP 5.2.X и более ранние версии
class Vendor_Model_Foo
{
}

4. Константы, свойства и методы классов.

Требования, указанные ниже к термину «класс», относятся ко всем классам, интерфейсам и трейтам.

4.1. Константы.

Константы классов ДОЛЖНЫ быть объявлены в верхнем регистре с использованием символа нижнего подчеркивания «_» в качестве разделителя. Для примера:

1
2
3
4
5
6
7
8
<?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() стиле.

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *