PHPTime

PHP-FIG и разделяемые интерфейсы в PHP

Если два пакета принимают Psr\Log\LoggerInterface, им можно передать один и тот же логгер. С кэшем выбор сложнее: общий интерфейс упрощает интеграцию, а прикладной контракт задаёт правила, от которых зависит работа приложения.

Что стандартизирует PHP-FIG

PHP Framework Interoperability Group объединяет участников PHP-экосистемы вокруг общей задачи: сделать так, чтобы библиотеки и фреймворки могли работать вместе. Результат этой работы — рекомендации PSR (PHP Standards Recommendations). Одни задают соглашения для инструментов и структуры проекта, другие описывают программные контракты, которые могут принять независимые пакеты.

Одной из первых рекомендаций была PSR-0 для автозагрузки. В современном проекте обычно настраивают PSR-4 через Composer: префиксу пространства имён сопоставляют базовый каталог, а остальная часть имени класса определяет путь к файлу. Например, при сопоставлении Acme\Catalog\ с src/ класс Acme\Catalog\Cache\PsrProductCache лежит в src/Cache/PsrProductCache.php. Автозагрузка помогает найти класс, а общий интерфейс позволяет передать его экземпляр другому пакету.

Какие PSR встречаются в прикладном коде

PSRКонтрактГде применять
PSR-3Psr\Log\LoggerInterfaceЗапись прикладных и диагностических событий
PSR-6Psr\Cache\CacheItemPoolInterfaceРабота с объектами кэша, проверка попадания, отложенное сохранение
PSR-16Psr\SimpleCache\CacheInterfaceЧтение и запись значений по ключам, в том числе пакетные операции
PSR-7Интерфейсы HTTP-сообщений и потоковПередача запросов и ответов между компонентами
PSR-18Psr\Http\Client\ClientInterfaceОтправка HTTP-запросов из SDK и интеграций
PSR-11Psr\Container\ContainerInterfaceСовместимость инструментов, работающих с контейнерами зависимостей

Интерфейсы распространяются отдельными Composer-пакетами. Например, psr/log содержит контракт логирования, а конкретный логгер выбирают при сборке приложения. Если библиотека использует этот контракт публично, пакет с интерфейсом следует указать в её require. Диапазон версий выбирают по совместимости сигнатур и проверяют на каждой заявленной ветке, особенно если библиотека сама реализует интерфейс.

Как использовать общий интерфейс

Передавайте зависимость через конструктор. Класс получает готовый объект и может использовать его сразу, а настройки обработчиков, формата и места записи остаются в конфигурации приложения. Пример рассчитан на PHP 8.3–8.5 и установленный пакет psr/log.

PHP
<?php
declare(strict_types=1);

use Psr\Log\LoggerInterface;

final readonly class ImportReporter
{
    public function __construct(private LoggerInterface $logger) {}

    public function skipped(int $row, string $reason): void
    {
        // Передаём номер строки и причину отдельными полями.
        $this->logger->warning('Строка {row} пропущена', [
            'row' => $row,
            'reason' => $reason,
        ]);
    }
}

Заполнители вроде {row} дают реализации возможность подставлять значения из контекста. Формат вывода и сохранение полей зависят от настроек логгера. При передаче исключения используйте ключ exception: он предусмотрен PSR-3. Для теста можно передать логгер, записывающий вызовы в память, а когда запись не требуется — Psr\Log\NullLogger. Контейнер, если он есть, разрешает зависимость при сборке приложения. Прикладному классу достаточно получить сам логгер.

Где заканчиваются гарантии общего контракта

Совпадающая сигнатура — только часть совместимости. PSR задаёт и правила поведения. Например, клиент PSR-18 возвращает корректный HTTP-ответ со статусом 404 или 500 обычным путём. Код, которому важен результат запроса, проверяет статус ответа. При переходе с API, которое по умолчанию бросает исключения для таких статусов, эту ветку нужно учесть отдельно.

У PSR-16 значение null выглядит так же, как промах, если читать ключ с обычным значением по умолчанию. Когда важно различать эти случаи, передайте уникальный объект как значение по умолчанию и сравните результат с ним через ===. У PSR-6 для этого есть isHit() у элемента кэша. Связка has() и get() оставляет окно между двумя операциями: за это время запись может истечь или быть удалена.

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

Как написать адаптер для прикладного интерфейса

Представим, что каталог хранит в кэше название товара. Прикладному коду нужны две операции с конкретными типами, единый срок жизни записи и понятное поведение при промахе. Адаптер использует любой совместимый кэш PSR-16 и переводит его общий API в контракт каталога. Для примера нужен Composer-пакет psr/simple-cache и реализация его интерфейса.

PHP
<?php
declare(strict_types=1);

use Psr\SimpleCache\CacheInterface;

interface ProductNameCache
{
    public function find(int $productId): ?string;

    public function store(int $productId, string $name): bool;
}

final readonly class PsrProductNameCache implements ProductNameCache
{
    private const TTL_SECONDS = 300;

    public function __construct(private CacheInterface $cache) {}

    public function find(int $productId): ?string
    {
        $value = $this->cache->get($this->key($productId));

        // Значение другого типа считаем промахом.
        return is_string($value) ? $value : null;
    }

    public function store(int $productId, string $name): bool
    {
        // Передаём результат записи вызывающему коду.
        return $this->cache->set($this->key($productId), $name, self::TTL_SECONDS);
    }

    private function key(int $productId): string
    {
        return 'catalog.product_name.v1.' . $productId;
    }
}

get() возвращает mixed, поэтому адаптер проверяет тип даже с declare(strict_types=1). Строгий режим регулирует приведение скалярных типов и сам по себе не проверяет содержимое кэша. Пустая строка остаётся допустимым значением. При промахе сервис каталога может прочитать название из основного хранилища. Возврат false из store() сообщает о неудачной записи. Если реализация выбрасывает исключение, в этом примере оно доходит до вызывающего кода. Если каталог должен переживать недоступность кэша, определите, какие сбои можно трактовать как промах, и протестируйте этот сценарий.

Префикс ключа выделяет записи каталога в общем хранилище. Версия в ключе пригодится при изменении формата значения. Если имя товара зависит от языка или витрины, включите соответствующее измерение в ключ. Если имя должно обновляться сразу, предусмотрите инвалидирование при изменении товара: срок жизни сам по себе допускает выдачу старого значения до истечения записи.

Чек-лист выбора интерфейса

  1. Начните с требуемых операций. Если стандартный контракт покрывает нужное поведение, принимайте интерфейс PSR напрямую.
  2. Выразите прикладные правила типами. Если важны формат значения, правила промаха или специальные возможности, опишите их в собственном интерфейсе и свяжите его с библиотекой через адаптер.
  3. Собирайте зависимости в одном месте. В точке входа, фабрике или конфигурации контейнера выберите реализацию и передайте её через конструктор.
  4. Проверьте поведение при замене реализации. Для кэша прогоните попадание, промах, истечение срока и отказ записи. Для HTTP-клиента проверьте ответы с ошибочным статусом и сетевые сбои.
  5. Зафиксируйте публичные зависимости. Укажите их в Composer, используйте PSR-4 для автозагрузки и учитывайте семантическое версионирование при изменении публичных сигнатур или гарантий поведения.

Частые вопросы

Обязательны ли стандарты PHP-FIG для PHP-проекта?

PSR — рекомендации экосистемы. Проект принимает те из них, которые упрощают интеграцию. Если библиотека заявляет поддержку конкретного PSR, она должна соблюдать его сигнатуры и правила поведения.

Как выбрать между PSR-6 и PSR-16?

PSR-16 подходит для операций со значениями по ключу. PSR-6 удобен, когда нужны объекты элементов кэша, явная проверка попадания или отложенное сохранение. Для сторонней библиотеки начните с интерфейса, который она принимает.

Когда нужен собственный интерфейс поверх PSR?

Когда прикладному коду нужны более узкие типы или особые правила, например единый TTL для записей каталога либо явная гарантия атомарного обновления. Адаптер связывает эти требования с возможностями выбранной реализации.

Справка по теме

Ещё в разделе «Архитектура и практика»

Инверсия управления в PHP: Голливудский принцип

Разбираем принцип инверсии управления (IoC) в современном PHP: отличие от DI, события и наблюдатели, примеры на PHP 8.3–8.5, антипаттерны и чек-лист внедрения.

8 мин

Эффективный рефакторинг PHP-кода

Практическое руководство по рефакторингу в PHP 8.3–8.5. Как зафиксировать поведение тестами, усилить типизацию, разделить обязанности и удалить мёртвый код.

7 мин

Декаплинг и фреймворки в PHP: как перестать зависеть от чужих обновлений

Как отделить бизнес-логику от фреймворка в современных PHP-проектах. Интерфейсы, DTO, адаптеры, DI-контейнеры и стратегии миграции без остановки разработки.

7 мин

Как задать вопрос по PHP, чтобы получить ответ

Как задать вопрос по PHP: соберите минимальный воспроизводимый пример, укажите версии и условия запуска, приложите текст ошибки и выберите площадку.

7 мин