PSR Стандарты

Небольшая предыстория, которая вдохновила меня на написание этой статьи.

За последние полгода мне пришлось провести множество собеседований на позицию Middle PHP-Developer.

Один из вопросов, который я задавал всем кандидатам, был:- «Знаете ли Вы, что такое PSR?»



Как оказалось, практически всем кандидатам была знакома эта аббревиатура. Однако пытаясь рассказать подробнее, почти все разработчики указывали в основном на то, что это стандарт оформления кода (code style). Только некоторые упоминали про PSR-4 автозагрузку (использует Composer) и PSR-3 Logger Interface (в сети очень много однородных статей про PSR-0-1-2-3-4).

Мне кажется это весьма странным, так как термин PSR существует достаточно давно (уже более 10 лет) и каждый год набирает все большую популярность. Поэтому, думаю, будет неплохо собрать все в кучу и сделать обзор PSR стандартов.

PHP-FIG и PSR

Автозагрузка

class MyLib {
    private $CI;
    public function __construct()
    {
        $this->CI = &get_instance();

        $this->CI->load->library('encrypt');
        $this->CI->load->library('session');
        $this->CI->load->library('url');

        $this->CI->load->helper('captcha');
        $this->CI->load->helper('cookie');
        $this->CI->load->helper('email');
    }
    ...
}

• PSR-0 — Autoloading Standard Устарел
  После релиза пространства имен в 2009 году, в 2010 году был опубликован первый стандарт, который стал революцией в решении проблем автозагрузки классов и стал первым шагом на пути объединения фреймворков — наличие общей структуры директорий.
  Пример реализации
  
• PSR-4 — Autoloading Standard
  Прогресс не стоит на месте и в конце 2013 года PHP-FIG публикуют новый стандарт автозагрузки классов. Он может использоваться в дополнение к PSR-0, а также любой другой спецификации автозагрузки. Стандарт также описывает, где размещать файлы, которые будут автоматически загружаться в соответствии со спецификацией. Данный стандарт решает некоторые проблемы/ограничения PSR-0 и используется по умолчанию в Composer.
  Пример реализации
  

Интерфейсы

• PSR-3: Logger Interface
  Основная цель данного интерфейса – простым и универсальным способом стандартизировать реализацию логирования. К данному интерфейсу прилагается спецификация, которая описывает в каких случаях какой из методов рекомендуется использовать.
  
  LoggerInterface

  interface LoggerInterface
  {
      public function emergency($message, array $context = array());
      public function alert($message, array $context = array());
      public function critical($message, array $context = array());
      public function error($message, array $context = array());
      public function warning($message, array $context = array());
      public function notice($message, array $context = array());
      public function info($message, array $context = array());
      public function debug($message, array $context = array());
      public function log($level, $message, array $context = array());
  }

  
  
  
  Если Ваш проект нуждается в расширенном функционале, МОЖНО расширять данный интерфейс, но СЛЕДУЕТ сохранять совместимость с описанными в данном стандарте правилами. Это позволит сторонним библиотекам, применяемых при разработке приложения, использовать централизованную систему логирования.
  
  На сегодняшний день нет необходимости самостоятельно реализовывать данный интерфейс (разве что в целях обучения), так-как существует отличное решение Monolog для реализации логирования, которое используется во многих проектах.
  
• PSR-6: Caching Interface
  Кэширование широко используется для повышения производительности любого проекта.
  Кэширование так-же является одной из наиболее распространенных функций многих CMS, фреймворков и библиотек.
  
  Это привело к ситуации, когда многие библиотеки реализуют свои собственные системы кэширования с различными уровнями функциональности. Эти различия заставляют разработчиков изучать несколько систем, которые могут предоставлять или не предоставлять необходимую им функциональность. Кроме того, разработчики кеширующих библиотек сами сталкиваются с выбором между поддержкой только ограниченного числа платформ или созданием большого количества классов адаптеров.
  
  Чтобы решить эти проблемы был принят общий стандарт для библиотек реализующих кэширование, он включает в себя несколько интерфейсов:
  
  CacheItemInterface и CacheItemPoolInterface

  interface CacheItemInterface
  {
      public function getKey();
      public function get();
      public function isHit();
      public function set($value);
      public function expiresAt($expiration);
      public function expiresAfter($time);
  }

  
  

  interface CacheItemPoolInterface
  {
      public function getItem($key);
      public function getItems(array $keys = array());
      public function hasItem($key);
      public function clear();
      public function deleteItem($key);
      public function deleteItems(array $keys);
      public function save(CacheItemInterface $item);
      public function saveDeferred(CacheItemInterface $item);
      public function commit();
  }
  

  
  
  
  Наверное самая годная реализация PSR-6 это Symfony Cache. А вот одна из самых старых реализаций — это Laminas Cache (бывший Zend).
  
• PSR-11: Container Interface
  Основная цель стандартизировать, как фреймворки и библиотеки будут использовать (DIC) контейнер для доступа к объектам и параметрам. Для этого был описан ContainerInterface.
  
  ContainerInterface

  interface ContainerInterface
  {
      public function get($id);
      public function has($id);
  }

  
  
  
  Спецификация PSR-11 не описывает то, как необходимо регистрировать зависимости в проекте, однако дает четкую рекомендацию как делать не нужно:
  

  Пользователи НЕ ДОЛЖНЫ передавать контейнер в объект, чтобы объект мог получить свои собственные зависимости. Это означает, что контейнер используется в качестве Service Locator, который обычно не рекомендуется использовать.
  

  Отсюда, возникает простой вопрос: «Как это вообще работает»?
  
  На самом деле все просто, на помощь приходит паттер Factory, который возьмет на себя задачу создания объекта. А вот сам класс фабрики уже может принимать ContainerInterface и передавать в создаваемый объект необходимые зависимости.
  
  Пример кода

  ConfigProvider
  

  [
      'invokables' => [
            // можно обойтись без фабрики, если класс не требует зависимостей
      ],
      'factories'  => [
          MyHandler::class => MyHandlerFactory::class,
      ],
  ];

  
  MyHandlerFactory
  

  class MyHandlerFactory
  {
      public function __invoke(ContainerInterface $container) : RequestHandlerInterface
      {
          $dep = $container->get(MyDepInterface::class);
  
          return new MyHandler($dep);
      }
  }

  
  MyHandler
  

  class MyHandler
  {
      private $dep;
      public function __construct(MyDepInterface $dep) 
      {
          $this->dep = $dep;
      }
      public function __invoke(ServerRequestInterface $request): RequestHandlerInterface
      {
           //
      }
  }

  
  
  
  Данный подход использует middleware framework Mezzio (это бывший Zend Expressive), что позволяет соблюдать принципы SOLID и получить дополнительную гибкость при создании объектов.
  
• PSR-13: Hypermedia Links
  Не самый популярный стандарт, который предоставляет несколько интерфейсов, чтобы унифицировать общий формат hypermedia ссылок.
  
  LinkInterface, EvolvableLinkInterface и LinkProviderInterface EvolvableLinkProviderInterface

  LinkInterface
  

  interface LinkInterface
  {
      public function getHref();
      public function isTemplated();
      public function getRels();
      public function getAttributes();
  }

  
  EvolvableLinkInterface
  

  interface EvolvableLinkInterface extends LinkInterface
  {
      public function withHref($href);
      public function withRel($rel);
      public function withoutRel($rel);
      public function withAttribute($attribute, $value);
      public function withoutAttribute($attribute);
  }

  
  LinkProviderInterface
  

  interface LinkProviderInterface
  {
      public function getLinks();
      public function getLinksByRel($rel);
  }

  
  EvolvableLinkProviderInterface
  

  interface EvolvableLinkProviderInterface extends LinkProviderInterface
  {
      public function withLink(LinkInterface $link);
      public function withoutLink(LinkInterface $link);
  }

  
  
  
  В качестве примера, можно рассмотреть использование hypermedia ссылок в контексте HTML и в различных форматах API. При этом, если контекст использования ссылок в HTML понятен, то с API поможет разобраться статья "Hypermedia — то без чего Ваше API не совсем REST".
  Примеров использования данного стандарта не много: Symfony Web Link и Html Model.
  
• PSR-14: Event Dispatcher
  Целью этого PSR является создание общего механизма для диспетчеризации событий, чтобы библиотеки и компоненты могли свободно использоваться в различных приложениях и средах. Для этого предоставляется несколько интерфейсов:
  
  EventDispatcherInterface, ListenerProviderInterface и StoppableEventInterface

  EventDispatcherInterface
  

  interface EventDispatcherInterface
  {
      public function dispatch(object $event);
  }

  
  ListenerProviderInterface
  

  interface ListenerProviderInterface
  {
      public function getListenersForEvent(object $event) : iterable;
  }

  
  StoppableEventInterface
  

  interface StoppableEventInterface
  {
      public function isPropagationStopped() : bool;
  }

  
  
  
  Диспетчеризация событий — это распространенный и хорошо протестированный механизм, позволяющий разработчикам легко и последовательно расширять логику приложения. Детально данный стандарт хорошо описывает статья "PSR-14 — главное событие в PHP".
  Чтобы попробовать в действии, предлагаю взглянуть на реализацию Symfony Event Dispatcher, YiiSoft Event Dispatcher и другие.
  
• PSR-16: Simple Cache
  Обратите внимание на PSR-6, это действительно «мощная» спецификация для реализации системы кеширования, однако в большинстве проектов такая реализация может оказаться избыточной.
  
  Поэтому был принят PSR-16. Этот более простой подход направлен на создание стандартизированного оптимизированного интерфейса для общих случаев.
  
  CacheInterface

  interface CacheInterface
  {
      public function get($key, $default = null);
      public function set($key, $value, $ttl = null);
      public function delete($key);
      public function clear();
      public function getMultiple($keys, $default = null);
      public function setMultiple($values, $ttl = null);
      public function deleteMultiple($keys);
      public function has($key);
  }

  
  
  
  В списке реализаций все тот-же Symfony Cache и Laminas Cache (бывший Zend).
  

HTTP

• PSR-7: HTTP Message Interfaces
  Цель данного стандарта, предоставить общий набор интерфейсов для фреймворков, чтобы последние могли использовать одинаковые абстракции над Request и Response объектами. Это позволит разработчикам писать переиспользуемый, независимый от фреймворка код. Спецификация данного стандарта достаточно объемна:
  
  MessageInterface, RequestInterface, ServerRequestInterface, ResponseInterface, StreamInterface, UriInterface и UploadedFileInterface

  MessageInterface
  

  interface MessageInterface
  {
      public function getProtocolVersion();
      public function withProtocolVersion($version);
      public function getHeaders();
      public function hasHeader($name);
      public function getHeader($name);
      public function getHeaderLine($name);
      public function withHeader($name, $value);
      public function withAddedHeader($name, $value);
      public function withoutHeader($name);
      public function getBody();
      public function withBody(StreamInterface $body);
  }

  
  RequestInterface
  

  interface RequestInterface extends MessageInterface
  {
      public function getRequestTarget();
      public function withRequestTarget($requestTarget);
      public function getMethod();
      public function withMethod($method);
      public function getUri();
      public function withUri(UriInterface $uri, $preserveHost = false);
  }

  
  ServerRequestInterface
  

  interface ServerRequestInterface extends RequestInterface
  {
      public function getServerParams();
      public function getCookieParams();
      public function withCookieParams(array $cookies);
      public function getQueryParams();
      public function withQueryParams(array $query);
      public function getUploadedFiles();
      public function withUploadedFiles(array $uploadedFiles);
      public function getParsedBody();
      public function withParsedBody($data);
      public function getAttributes();
      public function getAttribute($name, $default = null);
      public function withAttribute($name, $value);
      public function withoutAttribute($name);
  }

  
  ResponseInterface
  

  interface ResponseInterface extends MessageInterface
  {
      public function getStatusCode();
      public function withStatus($code, $reasonPhrase = '');
      public function getReasonPhrase();
  }

  
  StreamInterface
  

  interface StreamInterface
  {
      public function __toString();
      public function close();
      public function detach();
      public function getSize();
      public function tell();
      public function eof();
      public function isSeekable();
      public function seek($offset, $whence = SEEK_SET);
      public function rewind();
      public function isWritable();
      public function write($string);
      public function isReadable();
      public function read($length);
      public function getContents();
      public function getMetadata($key = null);
  }

  
  UriInterface
  

  interface UriInterface
  {
      public function getScheme();
      public function getAuthority();
      public function getUserInfo();
      public function getHost();
      public function getPort();
      public function getPath();
      public function getQuery();
      public function getFragment();
      public function withScheme($scheme);
      public function withUserInfo($user, $password = null);
      public function withHost($host);
      public function withPort($port);
      public function withPath($path);
      public function withQuery($query);
      public function withFragment($fragment);
      public function __toString();
  }

  
  UploadedFileInterface
  

  interface UploadedFileInterface
  {
      public function getStream();
      public function moveTo($targetPath);
      public function getSize();
      public function getError();
      public function getClientFilename();
      public function getClientMediaType();
  }

  
  
  
  А более детальное описание с примерами можно разобрать в статье "PSR-7 в примерах".
  
  Laminas Diactoros (бывший Zend Diactoros) — является отличной реализацией PSR-7. И при этом в экосистеме PHP популярны симфони компоненты, среди которых Symfony HTTP-Foundation. Данный компонент не реализовал поддержку PSR-7, но предоставил мост, который ранее работал через Zend Diactoros, но сейчас использует другую имплементацию psr-7.
  
• PSR-15: HTTP Handlers
  Спецификация данного стандарта описывает интерфейсы для обработчиков HTTP-запросов
  и компонентов промежуточного программного обеспечения HTTP-сервера.
  
  RequestHandlerInterface и MiddlewareInterface

  RequestHandlerInterface
  

  interface RequestHandlerInterface
  {
      public function handle(ServerRequestInterface $request): ResponseInterface;
  }

  
  MiddlewareInterface
  

  interface MiddlewareInterface
  {
      public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface;
  }

  
  
  
  Если не вдаваться во все тонкости, то по сути это возможность писать некие абстрактные контроллеры для последующего переиспользования между различными проектами.
  
  Middleware framework Mezzio (бывший Zend Expressie) отлично демонстрирует примеры реализации PSR-15.
  
• PSR-17: HTTP Factories
  PSR-17 описывает общий стандарт для фабрик, которые создают HTTP-объекты, совместимые с PSR-7.
  
  PSR-7 не содержит рекомендации о том, как создавать HTTP-объекты. Это может приводить к трудностям при необходимости их создания внутри компонентов, которые не привязаны к конкретной реализации PSR-7.
  
  Интерфейсы, описанные в этой спецификации, описывают методы, с помощью которых можно создавать PSR-7 объекты.
  
  RequestFactoryInterface, ResponseFactoryInterface, ServerRequestFactoryInterface, StreamFactoryInterface, UploadedFileFactoryInterface и UriFactoryInterface

  RequestFactoryInterface
  

  interface RequestFactoryInterface
  {
      public function createRequest(string $method, $uri): RequestInterface;
  }

  
  ResponseFactoryInterface
  

  interface ResponseFactoryInterface
  {
      public function createResponse(int $code = 200, string $reasonPhrase = ''): ResponseInterface;
  }

  
  ServerRequestFactoryInterface
  

  interface ServerRequestFactoryInterface
  {
      public function createServerRequest(string $method, $uri, array $serverParams = []): ServerRequestInterface;
  }

  
  StreamFactoryInterface
  

  interface StreamFactoryInterface
  {
      public function createStream(string $content = ''): StreamInterface;
      public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface;
      public function createStreamFromResource($resource): StreamInterface;
  }

  
  UploadedFileFactoryInterface
  

  interface UploadedFileFactoryInterface
  {
      public function createUploadedFile(
          StreamInterface $stream,
          int $size = null,
          int $error = \UPLOAD_ERR_OK,
          string $clientFilename = null,
          string $clientMediaType = null
      ): UploadedFileInterface;
  }

  
  UriFactoryInterface
  

  interface UriFactoryInterface
  {
      public function createUri(string $uri = '') : UriInterface;
  }

  
  
  
  Посмотреть пример использования PSR-17 можно в простой реализации PSR-7.
  
• PSR-18: HTTP Client
  PSR-18 описывает общие интерфейсы для отправки PSR-7 HTTP-запросов и получения HTTP-ответов.
  
  ClientInterface, RequestExceptionInterface и NetworkExceptionInterface

  ClientInterface
  

  interface ClientInterface
  {
      public function sendRequest(RequestInterface $request): ResponseInterface;
  }

  
  RequestExceptionInterface
  

  interface RequestExceptionInterface extends ClientExceptionInterface
  {
      public function getRequest(): RequestInterface;
  }

  
  NetworkExceptionInterface
  

  interface NetworkExceptionInterface extends ClientExceptionInterface
  {
      public function getRequest(): RequestInterface;
  }

  
  
  
  Это может сделать библиотеки более пригодными для повторного использования, так как уменьшает количество зависимостей и снижает вероятность конфликтов версий.
  
  Также в спецификации указано, что HTTP-клиенты могут быть заменены согласно принципу подстановки Лисков. Это означает, что все клиенты ДОЛЖНЫ вести себя одинаково при отправке запроса.
  
  Пример реализации PSR-18 можно увидеть в библиотеке Symfony HTTP-client.
  

Стиль кодирования

• PSR-1: Basic Coding Standard
  
• PSR-2 — Coding Style Guide Устарел
  
• PSR-12: Extended Coding Style Guide
  

• Использование только тэгов <?php и <?=
• Только UTF-8 без BOM для php кода
• Не стоит мешать разный функционал в одном файле (1 файл = 1 класс)
• Пространство имен и классы должны следовать [PSR-0, PSR-4]
• Классы объявляются в `StudlyCase`
• Константы объявляются в ТАКОМ_ВИДЕ
• Методы объявляются в `camelCase`

• Ручной режим: можно использовать reformat code в phpStorm.
• Более продвинутый вариант: использовать какой-нибуть кодснифер, например PHP CS Fixer (часто используется в CI, чтобы не принимать коммиты с неотформатированным кодом).

Преимущества использования PSR

И в заключение