psr 0 4 пример кода
Хроники детерминированности
(об IT, обучении, обучении в IT)
Перевод стандартов PSR-0, PSR-1, PSR-2, PSR-3, PSR-4
Этот (да-да, очередной) перевод был сделан потому, что существующие переводы (при всём глубоком уважении к их авторам) либо не покрывают все PSR-стандарты, либо частично устарели, либо по каким-то иным причинам меня не устроили. Итак…
Перевод стандартов PSR-0, PSR-1, PSR-2, PSR-3, PSR-4
Альтернативные переводы PSR на русский язык можно найти здесь:
Принятые стандарты
PSR-0 – Стандарт автозагрузки
Ниже представлены требования, обязательные к исполнению в целях обеспечения совместимости механизмов автозагрузки.
Знак подчёркивания в именах пространств имён и классов
Представленные здесь стандарты должны восприниматься как минимально необходимый набор правил для обеспечения совместимости автозагрузчиков. Вы можете проверить, насколько вы следуете указанным правилам, воспользовавшись следующим примером реализации SplClassLoader (ориентирован на загрузку классов PHP 5.3).
Ниже представлен пример функции, иллюстрирующей, как описанные выше требования влияют на процесс автозагрузки:
PSR-1 – Базовый стандарт оформления кода
Данный раздел описывает стандартные элементы, являющиеся существенными для обеспечения высокой технической совместимости кода, созданного и/или поддерживаемого различными разработчиками.
Слова «НЕОБХОДИМО» / «ДОЛЖНО» («MUST»), «НЕДОПУСТИМО» («MUST NOT»), «ТРЕБУЕТСЯ» («REQUIRED»), «НУЖНО» («SHALL»), «НЕ ПОЗВОЛЯЕТСЯ» («SHALL NOT»), «СЛЕДУЕТ» («SHOULD»), «НЕ СЛЕДУЕТ» («SHOULD NOT»), «РЕКОМЕНДУЕТСЯ» («RECOMMENDED»), «МОЖЕТ» / «ВОЗМОЖНО» («MAY») и «НЕОБЯЗАТЕЛЬНО» («OPTIONAL») в этом документе следует понимать так, как это описано в RFC 2119 (и его переводе).
PHP-код ОБЯЗАТЕЛЬНО следует заключать в полную версию ( ) тегов или укороченную (сокращённую запись echo) версию ( ) тегов и НЕДОПУСТИМО заключать ни в какие иные разновидности тегов.
2.2. Кодировка символов
PHP-код ДОЛЖЕН быть представлен только в кодировке UTF-8 без BOM-байта.
2.3. Побочные эффекты
В файлах СЛЕДУЕТ либо объявлять структуры (классы, функции, константы и т.п.) и не создавать побочных эффектов (например: передавать данные в выходной поток, модифицировать настройки и т.п.), либо реализовывать логику, порождающую побочные эффекты, но НЕ СЛЕДУЕТ делать одновременно и то, и другое.
Под «побочными эффектами» понимается реализация логики, не связанной с объявлением классов, функций, констант и т.п. – даже подключение внешнего файла уже является «побочным эффектом».
Ниже представлен пример файла, содержащий в себе как объявления структур, так и порождение побочных эффектов, т.е. ситуации, которой стоит избегать:
Следующий пример демонстрирует файл с объявлениями без побочных эффектов – т.е. образец рекомендуемой реализации:
3. Имена пространств имён и имена классов
Имена пространств имён и имена классов ДОЛЖНЫ следовать стандарту PSR-0. В конечном итоге это означает, что каждый класс должен располагаться в отдельном файле и в пространстве имён с хотя бы одним верхним уровнем (именем производителя).
Имена классов ДОЛЖНЫ быть объявлены с использованием т.н. « StudlyCaps » (каждое слово начинается с большой буквы, между словами нет разделителей).
Код, написанный для PHP 5.3 и более новых версий, ДОЛЖЕН использовать формальные пространства имён, например:
В коде, написанном для PHP 5.2.x и ниже, СЛЕДУЕТ при именовании классов соблюдать соглашение о псевдопространствах имён с префиксом в виде имени производителя ( Vendor_ ):
4. Константы, свойства и методы классов
Здесь под «классом» следует понимать также интерфейсы ( interface ) и примеси ( trait ).
Константы классов ДОЛЖНЫ быть объявлены в верхнем регистре с использованием символа подчёркивания в качестве разделителя слов, например:
Какой бы вариант именования ни был выбран, СЛЕДУЕТ сохранять его неизменным в рамках некоторого разумного объёма кода (например, на уровне производителя, пакета, класса или метода).
Имена методов ДОЛЖНЫ быть объявлены с использованием т.н. « camelCase » (первое слово пишется в нижнем регистре, далее каждое слово начинается с большой буквы, а между словами нет разделителей).
PSR-2 – Рекомендации по оформлению кода
Данные рекомендации расширяют и дополняют базовый стандарт оформления кода PSR-1.
Цель данных рекомендаций – снижение сложности восприятия кода, написанного разными авторами; она достигается путём рассмотрения серии правил и ожиданий относительно форматирования PHP-кода.
Стилистические правила, представленные здесь, получены путём обобщения опыта различных проектов. Сотрудничество многих авторов из многих проектов позволяет выработать единый набор принципов и использовать его в этих проектах. Таким образом, польза представленных рекомендаций – не столько в самих рекомендациях, сколько в их распространении.
Слова «НЕОБХОДИМО» / «ДОЛЖНО» («MUST»), «НЕДОПУСТИМО» («MUST NOT»), «ТРЕБУЕТСЯ» («REQUIRED»), «НУЖНО» («SHALL»), «НЕ ПОЗВОЛЯЕТСЯ» («SHALL NOT»), «СЛЕДУЕТ» («SHOULD»), «НЕ СЛЕДУЕТ» («SHOULD NOT»), «РЕКОМЕНДУЕТСЯ» («RECOMMENDED»), «МОЖЕТ» / «ВОЗМОЖНО» («MAY») и «НЕОБЯЗАТЕЛЬНО» («OPTIONAL») в этом документе следует понимать так, как это описано в RFC 2119 (и его переводе).
Следующий пример охватывает часть из вышеописанных правил:
2. Основные положения
2.1. Базовый стандарт оформления кода
Код ДОЛЖЕН быть оформлен согласно всем правилам, указанным в стандарте PSR-1.
Для оформления отступов ДОЛЖНЫ использоваться четыре пробела (но не знак табуляции).
Примечание: использование только лишь пробелов (без смешивания их с табуляциями) позволяет избежать проблем с обработкой истории изменения кода, определением самих изменений, патчами и комментариями. Использование пробелов также позволяет легко добавлять небольшие отступы для выравнивания отдельных вложенных строк.
2.5. Ключевые слова и константы true / false / null
3. Определение пространств имён и блоков импорта
4. Классы, свойства и методы
Здесь под «классом» следует понимать также интерфейсы ( interface ) и примеси ( trait ).
4.1. Наследование и реализация
В общем случае определение свойства выглядит так:
В общем случае определение метода выглядит так. Обратите внимание на круглые скобки, запятые, пробелы и фигурные скобки:
4.4. Аргументы методов
4.5. Ключевые слова abstract, final и static
4.6. Вызовы методов и функций
В коде вызова функций и методов НЕ ДОЛЖНО быть пробела между именем функции или метода и открывающей круглой скобкой, НЕ ДОЛЖНО быть пробела после открывающей круглой скобки, НЕ ДОЛЖНО быть пробела перед закрывающей круглой скобкой. В списке аргументов НЕ ДОЛЖНО быть пробелов перед запятыми, но ДОЛЖЕН быть пробел после каждой запятой.
Список аргументов МОЖЕТ быть разделён на несколько строк, каждая из которых дополнена слева одним отступом (четырьмя пробелами). В таком случае первый элемент списка аргументов ДОЛЖЕН начинаться с новой строки, и в каждой строке ДОЛЖЕН быть указан только один аргумент.
5. Управляющие конструкции
Общие правила оформления управляющих конструкций:
Тело каждой управляющей конструкции ДОЛЖНО быть заключено в фигурные скобки. Это позволяет стандартизировать внешний вид управляющих конструкций с снизить риск возникновения ошибок при добавлении новых строк в тело конструкции.
5.1. Конструкции if, elseif и else
Конструкция if выглядит следующим образом. Обратите внимание на круглые скобки, пробелы и фигурные скобки, а также на тот факт, что слова else и elseif располагаются в той же строке, что и закрывающая фигурная скобка предшествующего тела конструкции.
5.2. Конструкции switch и case
5.3. Конструкции while и do while
Конструкция while выглядит следующим образом. Обратите внимание на круглые скобки, пробелы и фигурные скобки.
Соответственно, конструкция do while выглядит следующим образом. Обратите внимание на круглые скобки, пробелы и фигурные скобки.
5.4. Конструкция for
Конструкция for выглядит следующим образом. Обратите внимание на круглые скобки, пробелы и фигурные скобки.
5.5. Конструкция foreach
Конструкция foreach выглядит следующим образом. Обратите внимание на круглые скобки, пробелы и фигурные скобки.
5.6. Конструкция try catch
Блоки конструкции try catch выглядят следующим образом. Обратите внимание на круглые скобки, пробелы и фигурные скобки.
Описание замыкания выглядит следующим образом. Обратите внимание на круглые скобки, запятые, пробелы и фигурные скобки.
Список аргументов и переменных МОЖЕТ быть разделён на несколько строк, каждая из которых дополнена слева одним отступом (четырьмя пробелами). В таком случае первый элемент списка ДОЛЖЕН начинаться с новой строки, и в каждой строке ДОЛЖЕН быть указан только один элемент.
Когда последний список (аргументов или переменных) разделён на несколько строк, закрывающая круглая скобка и открывающая фигурная скобка ДОЛЖНЫ располагаться на одной строке и быть разделены одним пробелом.
Ниже представлены примеры замыканий со списком аргументов и без него, а также со списком переменных, располагающимся на нескольких строках.
Обратите внимание, что правила оформления замыканий также распространяются на случай, когда замыкание используется в качестве аргумента прямо в вызове функции или метода.
В этом руководстве намеренно не рассмотрены правила и лучшие практики по оформлению многих элементов, список которых включает в себя, но не ограничивается следующим:
В будущем данные рекомендации МОГУТ быть пересмотрены и расширены, чтобы охватить те или иные элементы кода и практики оформления.
Приложение A. Опрос
Примечание переводчика: в оригинальном тексте стандарта содержится приложение с результатами опроса, на основе которого были приняты те или иные решения. Приложение представляет собой большой массив неудобочитаемых данных и не несёт явной пользы для понимания стандарта. Вы всегда можете ознакомиться с представленными там данными здесь: http://www.php-fig.org/psr/psr-2/.
PSR-3 – Интерфейс протоколирования
Данный документ описывает общий интерфейс библиотек протоколирования.
Основная цель данного документа – позволить библиотекам получать объект Psr\Log\LoggerInterface и использовать его простым и универсальным образом для реализации протоколирования. В случае, если некий фреймворк или CMS нуждается в расширенном функционале, МОЖНО расширять данный интерфейс, но СЛЕДУЕТ сохранять совместимость с описанными в данном документе правилами. Это позволит сторонним библиотекам, применяемым при разработке приложения, использовать централизованную систему протоколирования.
Слова «НЕОБХОДИМО» / «ДОЛЖНО» («MUST»), «НЕДОПУСТИМО» («MUST NOT»), «ТРЕБУЕТСЯ» («REQUIRED»), «НУЖНО» («SHALL»), «НЕ ПОЗВОЛЯЕТСЯ» («SHALL NOT»), «СЛЕДУЕТ» («SHOULD»), «НЕ СЛЕДУЕТ» («SHOULD NOT»), «РЕКОМЕНДУЕТСЯ» («RECOMMENDED»), «МОЖЕТ» / «ВОЗМОЖНО» («MAY») и «НЕОБЯЗАТЕЛЬНО» («OPTIONAL») в этом документе следует понимать так, как это описано в RFC 2119 (и его переводе).
Слово «разработчик» (implementor) в данном документе следует понимать как «автор, реализующий интерфейс LoggerInterface в неких библиотеке или фреймворке, связанных с протоколированием». Пользователи систем протоколирования упоминаются как просто «пользователи».
Интерфейс LoggerInterface предоставляет восемь методов протоколирования, соответствующих восьми уровням протоколирования, описанным в RFC 5424 (отладка ( debug ), информация ( info ), замечание ( notice ), предупреждение ( warning ), ошибка ( error ), критическая ошибка ( critical ), тревога ( alert ), авария ( emergency )).
Девятый метод, «протокол» ( log ) принимает в качестве первого аргумента уровень протоколирования. Вызов этого метода с передачей константы одного из уровней протоколирования ДОЛЖЕН приводить к тому же результату, что и вызов соответствующего переданному уровню протоколирования специального метода.
Вызов этого метода с передачей уровня протоколирования, не описанного в данной спецификации, ДОЛЖЕН приводить к порождению исключения Psr\Log\InvalidArgumentException в случае, если конкретная реализация системы протоколирования не поддерживает переданный уровень протоколирования.
Пользователям НЕ СЛЕДУЕТ использовать собственные уровни протоколирования без полной уверенности в том, что конкретная реализация системы протоколирования их поддерживает.
Ниже для ознакомления представлен пример обработки плейсхолдеров.
1.4 Вспомогательные классы и интерфейсы
3. Интерфейс Psr\Log\LoggerInterface
4. Интерфейс Psr\Log\LoggerAwareInterface
5. Класс Psr\Log\LogLevel
PSR-4 – Улучшенная автозагрузка
Слова «НЕОБХОДИМО» / «ДОЛЖНО» («MUST»), «НЕДОПУСТИМО» («MUST NOT»), «ТРЕБУЕТСЯ» («REQUIRED»), «НУЖНО» («SHALL»), «НЕ ПОЗВОЛЯЕТСЯ» («SHALL NOT»), «СЛЕДУЕТ» («SHOULD»), «НЕ СЛЕДУЕТ» («SHOULD NOT»), «РЕКОМЕНДУЕТСЯ» («RECOMMENDED»), «МОЖЕТ» / «ВОЗМОЖНО» («MAY») и «НЕОБЯЗАТЕЛЬНО» («OPTIONAL») в этом документе следует понимать так, как это описано в RFC 2119 (и его переводе).
Данный стандарт описывает спецификацию автозагрузки классов на основе путей к файлам. Он полностью совместим (и может использоваться как дополнение) с любой другой спецификацией автозагрузки, включая PSR-0. Данный стандарт также описывает правила размещения файлов, предназначенных для автозагрузки.
При загрузке файла, соответствующего полностью определённому имени класса, используются следующие правила:
В реализации автозагрузчика НЕДОПУСТИМО порождать исключения, ошибочные ситуации любого уровня и НЕ СЛЕДУЕТ возвращать какое бы то ни было значение.
В таблице ниже представлены примеры соответствий полностью определённого имени класса, префикса пространства имён, базового каталога и итогового пути к файлу.
Полностью определённое имя класса
Префикс пространства имён
Итоговый путь к файлу
Примеры реализации автозагрузчиков, соответствующих данной спецификации, представлены в файле с примерами. Примеры реализации НЕДОПУСТИМО рассматривать как часть спецификации, т.к. они МОГУТ измениться в любое время.
Подробнее о PSR-4. Улучшенная автозагрузка
PSR — это рекомендации по оформлению кода на PHP. Я писал ранее вводную статью об этом. Я хочу подготовить ряд статей о каждом из принятых на данный момент стандартов и поскольку нужно будет приводить много кода, то для каждого из стандартов будет отдельная статья. Я думал всю информацию уместить в один пост с примерами, но, как следует изучив вопрос понял, что это получится громадная простыня текста, которую сложно будет воспринять. Эта статья будет посвящена стандарту PSR-4. Пока что проработано 5 стандартов:
PSR-4 – Улучшенная автозагрузка
Слова «НЕОБХОДИМО» / «ДОЛЖНО» («MUST»), «НЕДОПУСТИМО» («MUST NOT»), «ТРЕБУЕТСЯ» («REQUIRED»), «НУЖНО» («SHALL»), «НЕ ПОЗВОЛЯЕТСЯ» («SHALL NOT»), «СЛЕДУЕТ» («SHOULD»), «НЕ СЛЕДУЕТ» («SHOULD NOT»), «РЕКОМЕНДУЕТСЯ» («RECOMMENDED»), «МОЖЕТ» / «ВОЗМОЖНО» («MAY») и «НЕОБЯЗАТЕЛЬНО» («OPTIONAL») в этом документе следует понимать так, как это описано в RFC 2119 (и его переводе).
Данный стандарт описывает спецификацию автозагрузки классов на основе путей к файлам. Он полностью совместим (и может использоваться как дополнение) с любой другой спецификацией автозагрузки, включая PSR-0. Данный стандарт также описывает правила размещения файлов, предназначенных для автозагрузки.
При загрузке файла, соответствующего полностью определённому имени класса, используются следующие правила:
В реализации автозагрузчика НЕДОПУСТИМО порождать исключения, ошибочные ситуации любого уровня и НЕ СЛЕДУЕТ возвращать какое бы то ни было значение.
В таблице ниже представлены примеры соответствий полностью определённого имени класса, префикса пространства имён, базового каталога и итогового пути к файлу.
Полностью определённое имя класса
Префикс пространства имён
Итоговый путь к файлу
Примеры реализации автозагрузчиков, соответствующих данной спецификации, представлены в файле с примерами. Примеры реализации НЕДОПУСТИМО рассматривать как часть спецификации, т.к. они МОГУТ измениться в любое время.
Стандарты кодирования PHP (PSR)
Группа взаимодействия фреймворков (PHP-FIG) окончательно приняла рекомендации к стандартам оформления кода на PHP.
Оригинальные тексты можно посмотреть на гитхабе.
PSR-0: требования к названиям классов
и неймспейсов для универсального автозагрузчика.
Полное имя класса должно быть вида `\ \( \)* `
PSR-1: Основные стандарты кодирования
Секция описывает общие правила оформления кода:
— Использование только тэгов
namespace Vendor\Package ;
use FooInterface ;
use BarClass as Bar ;
use OtherVendor\OtherPackage\BazClass ;
final public static function bar ( )
<
// method body
>
>
В голосовании по принятию стандартов участвовали разработчики таких проектов, как
Agavi
CakePHP, CakePHP 2
Chisimba, C4
Composer, Packagist
Doctrine, Doctrine2, et al.
Drupal
eZ Publish
FLOW3
Joomla
Lithium
PEAR, PEAR2
phpBB
PPI, PPI2
Propel, Propel 2
SabreDAV
Solar Framework, Aura Project
Symfony, Symfony2
Zend Framework, Zend Framework 2
Zikula
Соответствование требованием конкретных проектов можно посмотреть на
гугл докс
Но, сдавать код в общий проект будьте добры по тем правилам, которые установлены для всех (или в организации, где вы работаете). Стандарт на то и стандарт, чтобы любой разработчик мог открыть код и начать с ним работать, а не тратить время на его форматирование под себя.
PSR-4 на русском читать
Primary tabs
Forums:
Автозагрузчик
Ключевые слова «ДОЛЖНО» («MUST»), «НЕДОПУСТИМО» («MUST NOT»), «ТРЕБУЕТСЯ» («REQUIRED»), «НУЖНО» («SHALL»), «НЕ ПОЗВОЛЯЕТСЯ» («SHALL NOT»), «СЛЕДУЕТ» («SHOULD»), «НЕ СЛЕДУЕТ» («SHOULD NOT»), «РЕКОМЕНДУЕТСЯ» («RECOMMENDED»), «МОЖЕТ» («MAY») и «НЕОБЯЗАТЕЛЬНО» («OPTIONAL») в этом документе должны расцениваться так, как описано в RFC 2119.
1. Обзор
Данный PSR описывает спецификацию для автозагрузки классов на основе путей файлов. Она полностью взаимозаменяема и может использоваться в дополнение к любой другой спецификации автозагрузчика, включая PSR-0. Данный PSR также описывает, где размещать файлы, которые будут загружаться в соответствии со спецификацией.
2. Спецификация
Термин «класс» обозначает как классы, так и интерфейсы, трейты и другие подобные структуры.
Абсолютное имя класса имеет следующую форму:
При загрузке файла, соответствующего абсолютному имени класса:
В реализациях автозагрузчика НЕДОПУСТИМО выбрасывать исключения, НЕДОПУСТИМО вызывать ошибки любого уровня и НЕ СЛЕДУЕТ возвращать значение.
3. Примеры
В таблице ниже показано соответствие пути к файлу, абсолютного имени класса, префикса пространства имён и базовой директории.
Примеры реализации автозагрузчиков, соответствующих спецификации, приведены в файле примеров. НЕДОПУСТИМО рассматривать их как часть спецификации. Примеры МОГУТ измениться в любое время.
Primary tabs
Forums:
Основной стандарт написания кода
Этот раздел стандартов включает в себя что следует рассматривать как стандарт элементов кода, который необходим для обеспечения высокого уровня технической взаимодействия между общим PHP кодом.
Ключевые слова «ДОЛЖЕН», «НЕ ДОЛЖЕН», «ТРЕБУЕТСЯ», «БУДЕТ», «НЕ БУДЕТ», «СЛЕДУЕТ», «НЕ СЛЕДУЕТ», «РЕКОМЕНДУЕТСЯ», «МОЖЕТ», и «ДОПОЛНИТЕЛЬНО» в этом документе должны быть истолкованы как описано в RFC 2119.
1. Обзор
2. Файлы
теги или «короткие-выводящие»:
теги; другие варианты тегов НЕ ДОЛЖНЫ использоваться.
Фраза «побочные эффекты» означает:
выполнение логики непосредственно не связанной с объявлением классов, функций, констант и т.д., просто от включения файла.
«Побочные эффекты» включают, но не ограничены:
Ниже приведен пример файла с одновременно объявляющий знаки и оказывающий побочные эффекты; т.е., пример того, что следует избегать:
3. Пространства имен и Имена Классов
Это означает, что каждый класс находится в собственном файле, и в пространстве имен, по крайней мере, на один уровень: верхний уровень имя поставщика.
Имена классов ДОЛЖНЫ быть объявлены используя StudlyCaps.
Код написанный на PHP 5.3 и старше ДОЛЖЕН использовать формальные пространства имен.
В коде написанном для 5.2.x и раньше СЛЕДУЕТ использовать псевдо-пространства имен, условные приставки Vendor_ к именам классов.
4. Константы, Свойства, и Методы Класса
Термин «класс» относится ко всем классам, интерфейсам и трейтам.
4.1. Константы:
Константы класса ДОЛЖНЫ быть объявлены в верхнем регистре с подчеркиванием в качестве разделителей. Например:
4.2. Свойства:
Это руководство намеренно избегает любых рекомендаций, касающихся использования для имён свойств таких способов записи как:
Независимо от соглашения именования его СЛЕДУЕТ применять последовательно в разумных пределах. Этот предел может быть на уровне поставщика, на уровне пакета, на уровне класса, или уровне метода.
4.3. Методы:
Имена методов ДОЛЖНЫ быть объявлены используя camelCase.