Оглавление

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)

---

---

---

---

---

---

---

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