PSR (стандарты кодирования компонентов)
# -------------------------------------------------------------------
# PSR (стандарты кодирования компонентов)
# -------------------------------------------------------------------
// Стандартны (рекомендации) кодирования компонентов PSR (PHP standart recommendations)
// Каждый PSR освещает какую-то одну проблему, встречающуюся при разработке больших систем
// Сообщество PHP-FIG - https://www.php-fig.org/psr/
// https://github.com/php-fig/fig-standards/tree/master/accepted
// Утилиты для проверки кода:
// Утилита 1 (проверяет на PSR)
>> composer: добавить зависимость "squizlabs/php_codesniffer": "3.6.2"
>> запуск проверки: ./vendor/bin/phpcs --standard=PSR2 app/Models/
// Утилита 2 (проверяет сам код - возможные ошибки, несиользуемые параметры, методы и т.д.)
// Как пользоваться не разобрался - нужно создавать файл phpmd.xml
>> composer: добавить зависимость "phpmd/phpmd": "2.11.1"
>> ./vendor/bin/phpmd app/Models/ text // возможная команда:
// Утилита 3 (наиболее лучший вариант!)
>> https://github.com/FriendsOfPHP/PHP-CS-Fixer
>> composer require --working-dir=tools/php-cs-fixer friendsofphp/php-cs-fixer
// Дополнительно
// phpstan, phan, pslam
# -------------------------------------------------------------------
# PSR-1 основной стандарт кодирования
# -------------------------------------------------------------------
// *) только тэги <?php или <?=
// *) php-файлы только в кодировке UTF8 без BOM
// *) в файле содержится либо класс (функция, константа), либо их вызов, но ни то и не другое одновременно
// *) нельзя смешивать вывод и объявления функций
// *) пространства имен и классы должны соответствовать автозагрузке PSR-0, PSR-4
// *) имена классов в верблюжьей записи
// *) имена методов в верблюжьей записи (но первая буква в нижнем регистре)
// *) имена констант в классах пишутся прописными буквами с разделителями подчеркивания
# -------------------------------------------------------------------
# PSR-2 (новый PSR-12) руководство по единому стилю кодирования
# -------------------------------------------------------------------
// *) код должен соответствовать PSR-1
// *) PHP-файлы:
// - Окончание строки Unix LF (linefeed)
// - В конце 1 пустая строка
// - Без закрывающего тэга ?>
// *) Отступы 4 пробела вместо 1 таба в коде
// *) В начале файла после <?php нужно оставить 1 пустую строку
// *) После namespace нужно оставить 1 пустую строку (аналогично для use)
// *) Для классов, методов и других аналогов: фигурная скобка с новой строки и закрывающая также
// *) Для управляющих структур (if,switch ...)
// - после необходим 1 пробел
// - открывающая скобка располагается в той же строке, а закрывающая с новой строки
// *) Константы true, false, null нужно писать в нижнем регистре
// *) Все методы и члены классы должны предваряться модификатором (public, private ...)
// *) Аргументы метода (функции) - аналогично при передача аргументов в метод,
// а также при указании списка интерфейсов для класса, и при определении условий в конструкциях типа if( && ):
// - 1 пробел после запятой
// - если аргументов много допускается их перенос на новую строку с отступом
// - закрывающая фигурная скобка располагается с 1 пробелом ") {"
// *) Аргументы методов со значениями по умолчанию должны располагаться в конце списка
// *) Шаблон последовательности модификаторов <abstract||final> <видимость: piblic> <static> func|prop
// *) Наследование от класса (extends) пишется в 1 строку, подключение интерфейсов допускается разбить на несколько строк
// *) Длинна строки не более 80 (120) символов + не более 1 оператора
// Если ваша строка выходит за пределы рекомендуемой длины строки (120 символов), подумайте о конкатенации вашей строки
$a = 'Multi-line example' // concatenation operator (.)
. "\n" // indenting new lines
. 'of what to do';
# -------------------------------------------------------------------
# PSR-12 - новое
# -------------------------------------------------------------------
- При создании экземпляра нового класса круглые скобки всегда должны присутствовать, даже если конструктору не передаются аргументы (new Foo();)
- Необходимо использовать краткую форму ключевых слов типа, т. е. bool (вместо boolean)
- В многострочном варианте "if &&" условия с новой строки операторы ДОЛЖНЫ идти в начале строки "&& условие", а не в конце предыдущей
<?php
# PSR-2 (1 пустая строка)
namespace Username\Plugin;
# PSR-2 (1 пустая строка)
use Cake\Datasource\Exception\PageOutOfBoundsException;
use Couchbase\SearchOptions;
use http\Message;
# PSR-2 (1 пустая строка)
# PSR-`1` (название класса верблюд)
class Psr
{ # PSR-2 (скобка c с новой строки)
# PSR-1` (название константы в верхнем регистре)
const VERSION_NAME = 1;
public $id = 0;
# PSR-1 (название метода верблюд, но 1 буква с маленькой буквы)
# PSR-2 (последовательность модификаторов)
final public static function myFuncName(
$a = 0,
$b = 1
) { # PSR-2 (скобка c с новой строки)
if (isset($this->id)) { # PSR-2 (для управл.структур 1 пробел + открывающая скобка в той же строке)
$this->myFuncName();
$a = "fewfewfewew f ewf ew few few few few" . strlen("few") . strlen("efwfew") .
"few few few few few few few few few few few few few few few";
return null; # PSR-2 (константы true, false, null - в нижнем регистре)
}
}
}
# PSR-2 (1 пустая строка, отсутствует закрывающий тэг)
# -------------------------------------------------------------------
# PSR-4 (PSR-0) стандарт именования файлов, каталогов,
# стандарт автозагрузки файлов
# -------------------------------------------------------------------
// Описание пространства имен и имени класса - должны иметь следующую структуру:
// \<Имя поставщика Vendor Name>\<Имя пакета Package Name>\(<Namespace>\)*<Class Name>
// - Каждый разделитель пространства имен преобразуется в a DIRECTORY_SEPARATOR при загрузке из файловой системы.
// - Буквенные символы в именах поставщиков, пространствах имен и именах классов могут иметь любую комбинацию нижнего и верхнего регистра.
// - Пример: \Zend\Mail\Message => /path/to/project/lib/vendor/Zend/Mail/Message.php
// - Каждый php-класс размещается в отдельном файле
// - Классы объединяются в пакеты
// - Не желательно использовать подчеркивания в именах классов (это приводит к созданию доп. директории)
# -------------------------------------------------------------------
# PSR-5/19 (документирование кода)
# -------------------------------------------------------------------
// Утилита для генерации документации
>> composer require phpdocumentor/phpdocumentor 2.*
>> php ./vendor/bin/phpdoc -d folder -t doc
>> php ./vendor/bin/phpdoc -f file.php -t doc
>> php ./vendor/bin/phpdoc -V
>> php ./vendor/bin/phpdoc -h
>> php ./vendor/bin/phpdoc -d полный_путь_к_проЕкту -t полный_путь_к_папке_где_будет_храниться_документация
>> php ./vendor/bin/phpdoc -d D:\web\home\coder.local\www\
-t D:\web\home\coder.local\docs \
-ti 'Project name' \
-dn 'package name'
-pp on (включить закрытые методы в генерацию документации)
// В папке doc-появиться документация HTML-формата
>> php ./vendor/bin/phpdoc template:list
>> php ./vendor/bin/phpdoc -d D:\web\home\coder.local\www -t D:\web\home\coder.local\docs --template abstract
<?php
namespace Litovchenko\PhpDoc;
/**
* 1) Заголовок (имя) >> Пример документирования по PSR-5 (стандарт документирования объектов и методов)
*
* 2) Описание >> Подробное многострочное описание с примерами
* Команда PHPStorm на форматирование кода (Ctrl + Alt + L)
* Документированию могут подвергаться следующие элементы
* --> Файлы и пространства имен PHP
* --> require_once и другие аналогичные операторы
* --> Классы, интерфейсы, трейты, функции и методы классов
* --> Свойства классов, константы, переменные.
* --> Документирование конструкций типа foreach (для автозаполнения IDE)
*
* 3) Теги >> Метаинформация об элементах, каждый тег начинается с символа "@"*
* Типы данных:
* --> string
* --> integer (int), float
* --> boolean (bool)
* --> array
* --> resources
* --> null
* --> callable - функция обратного вызова
* --> mixed - любой из типов
* --> void - отсутствие возвращаемого значения
* --> object
* --> true или false - логические константы
*
* @author Ivan Litovchenko <iv-litovchenko@mail.ru>
* @author ...
* @copyright
*
* @see [URI | "FQSEN"] [<description>]
* @see number_of() :alias:
* @see MyClass::$items For the property whose items are counted.
* @see MyClass::setItems() To set the items for this collection.
* @see http://example.com/my/bar Documentation of Foo.
* @link http://example.com/my/bar Документация Foo.
* When no more Foo ({@link http://example.com/my/bar}) are given this
* @todo [description]
* @version ["Semantic Version"] [<description>]
*/
class ExamplePsr5
{
// @var ["Type"] [element_name] [<description>]
/** @var string Should contain a description */
const MY_CONST1 = "1";
// @var ["Type"] [element_name] [<description>]
/** @var int Некоторая переменная (однострочный вариант) */
public $peoples = [];
/**
* Некоторый метод класса (многострочный вариант)
*
* @param ["Type"] [element_name] [<description>]
* @param int $a Описание переменной a
* @param float $b Описание переменной b
* @param array|object $arr
*
* @return int|null|void
*/
public function myFuncName(
int $a = 0,
float $b = 1,
array $arr
) {
/** @var Person $people (подсветка синтаксиса для IDE) */
foreach ($this->peoples as $people) {
}
return null;
}
}
# -------------------------------------------------------------------
# Другие стандарты
# -------------------------------------------------------------------
- PSR-3 Интерфейс: стандарт протоколирования (журнал логов)
- PSR-6 Интерфейс: стандарт кэширования
- PSR-7 Интерфейс: стандарт сообщений и работы с HTTP (Request, Response, Server)
Здесь можно оставить комментарий!