PHPTime

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

Смена мажорной версии фреймворка не должна превращаться в rewrite всего проекта. Если ядро приложения связывается с HTTP-слоем и инфраструктурой через интерфейсы, а не через конкретные классы вендора, миграция становится инженерной задачей на несколько дней, а не катастрофой на квартал. Разберём, как достичь такого уровня независимости в современных PHP-проектах.

Почему фреймворк — это деталь реализации

Фреймворк решает инфраструктурные задачи: маршрутизация, DI-контейнер, работа с HTTP, валидация ввода, сериализация. Но если бизнес-правила начинают зависеть от конкретных реализаций этих механизмов, приложение попадает в ловушку. Смена версии с 6 на 7 может потребовать переписывания сотен сервисов, а переход на другой фреймворк вообще выглядит как новый проект.

На практике декаплинг — это не отказ от фреймворка. Это дисциплина проектирования, при которой код предметной области ничего не знает о HTTP-запросах, конкретных реализациях репозиториев и форматах ответа. Фреймворк остаётся полезным инструментом на границах приложения, но не проникает в его ядро.

Слои приложения и границы между ними

Типичное разделение на слои выглядит так:

  • Domain — сущности, value objects, доменные события, бизнес-правила. Никаких зависимостей от инфраструктуры.
  • Application — use case'ы, порты (интерфейсы) для репозиториев, транзакций, логирования, шины событий. Знает только о Domain и контрактах.
  • Infrastructure — реализации портов: Doctrine-репозитории, Redis-кэш, HTTP-клиенты, файловые хранилища. Здесь живёт код конкретного фреймворка.
  • UI — контроллеры, консольные команды, обработчики очередей. Адаптируют входящие сигналы к вызовам Application-сервисов.

Главное правило: зависимости направлены внутрь — от UI и Infrastructure к Application и Domain, но никогда наоборот. Domain и Application не должны содержать импортов из Symfony, Laravel или другого вендора.

Интерфейс как контракт, а не формальность

Когда бизнес-логика вызывает EntityManager напрямую, тестировать её можно только с реальной базой данных или сложным моком. Замена на интерфейс решает проблему: Application объявляет контракт, Infrastructure его реализует.

PHP
declare(strict_types=1);

namespace App\Application\Port;

interface OrderRepository
{
    public function findById(OrderId $id): ?Order;

    public function save(Order $order): void;
}

Реализация в Infrastructure может использовать Doctrine, Eloquent или даже API стороннего сервиса:

PHP
declare(strict_types=1);

namespace App\Infrastructure\Persistence;

use App\Application\Port\OrderRepository;
use Doctrine\ORM\EntityManagerInterface;

final class DoctrineOrderRepository implements OrderRepository
{
    public function __construct(
        private readonly EntityManagerInterface $em,
    ) {}

    public function findById(OrderId $id): ?Order
    {
        return $this->em->find(Order::class, $id);
    }

    public function save(Order $order): void
    {
        $this->em->persist($order);
        $this->em->flush();
    }
}

Application-сервис получает интерфейс через конструктор и не знает, какая реализация за ним стоит. Для тестов пишется in-memory заглушка, для продакшена — Doctrine. Если проект переезжает с Doctrine на Cycle ORM или на SQL через PDO, меняется только класс в DI-конфигурации.

DTO как буфер между HTTP и Application

Контроллеры часто получают доступ к сырому Request и передают его в сервисный слой. Из-за этого Application начинает зависеть от HTTP-семантики: методов get(), query(), headers(). DTO убирают эту зависимость.

PHP
declare(strict_types=1);

namespace App\Ui\Http\Dto;

final readonly class CreateOrderDto
{
    public function __construct(
        public string $customerEmail,
        public array $items,
    ) {}

    public static function fromRequest(ServerRequestInterface $request): self
    {
        $data = $request->getParsedBody();

        return new self(
            customerEmail: trim($data['email'] ?? ''),
            items: $data['items'] ?? [],
        );
    }
}

Контроллер отвечает за извлечение данных из HTTP-запроса и маппинг в DTO. Дальше работает типизированный объект:

PHP
final class CreateOrderAction
{
    public function __construct(
        private readonly CreateOrderHandler $handler,
    ) {}

    public function __invoke(ServerRequestInterface $request): ResponseInterface
    {
        $dto = CreateOrderDto::fromRequest($request);
        $order = $this->handler->handle($dto);

        return new JsonResponse(['id' => $order->id->value], 201);
    }
}

Миграция на другой HTTP-стек (например, с Laravel на Slim или с Symfony на RoadRunner) затрагивает только контроллеры и DTO-маппинг. Application-уровень не меняется.

Адаптеры для инфраструктурных сервисов

Кэш — классический пример протекающей абстракции. Если бизнес-логика вызывает $cache->get() из конкретной библиотеки, замена Redis на Memcached или на PSR-совместимый пул становится проблемой. Вводится собственный порт:

PHP
declare(strict_types=1);

namespace App\Application\Port;

interface Cache
{
    public function get(string $key): mixed;

    public function set(string $key, mixed $value, int $ttl): void;
}

В Infrastructure реализация оборачивает Symfony Cache, Laravel Cache или собственный Redis-клиент. Бизнес-логика работает только с контрактом. При смене бэкенда код ядра не трогается.

События и шина команд без привязки к конкретному транспорту

Если use case напрямую вызывает dispatch() из Symfony Messenger или Laravel Events, он привязывается к конкретной библиотеке. Правильный подход — доменные события и порт для публикации:

PHP
declare(strict_types=1);

namespace App\Domain\Event;

final readonly class OrderPlaced
{
    public function __construct(
        public string $orderId,
        public string $customerEmail,
    ) {}
}

В Application объявляется интерфейс шины:

PHP
declare(strict_types=1);

namespace App\Application\Port;

interface EventBus
{
    public function publish(object $event): void;
}

Реализация в Infrastructure использует нужный транспорт: RabbitMQ, Kafka, SQS или синхронный вызов подписчиков, если асинхронность не требуется. При переходе на другой брокер меняется только класс-адаптер.

Конфигурация DI: где происходит подмена реализаций

Декаплинг становится практикой только тогда, когда DI-контейнер конфигурируется осознанно. Бизнес-логика не должна знать, какая реализация интерфейса используется в данный момент. Настройка связываний выносится в отдельный файл конфигурации:

PHP
// config/di.php
return [
    OrderRepository::class => DoctrineOrderRepository::class,
    Cache::class => RedisCache::class,
    EventBus::class => RabbitMqEventBus::class,
];

Если проект переезжает с одной реализации на другую, меняется одно значение в конфигурации, а не код в двадцати местах. Для тестов используется отдельная конфигурация с in-memory реализациями.

Стратегия перехода: декаплинг без остановки разработки

Никто не может позволить себе остановить продуктовую разработку ради рефакторинга на три месяца. Поэтому декаплинг внедряется постепенно:

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

Когда большая часть ядра изолирована, смена фреймворка становится вопросом замены UI-слоя и адаптеров. Бизнес-логика остаётся прежней.

Чек-лист для проверки уровня декаплинга

  • В папке src/Domain нет ни одного импорта из сторонних библиотек, кроме PHP-расширений.
  • Application-сервисы получают зависимости через интерфейсы, объявленные в Application\Port.
  • Контроллеры не передают HTTP-объекты в сервисы — только типизированные DTO.
  • Каждый инфраструктурный сервис имеет собственный интерфейс-порт, даже если реализация использует готовый компонент фреймворка.
  • Подмена реализации в тестах занимает меньше пяти минут: достаточно заменить класс в DI-конфиге.
  • При поднятии мажорной версии фреймворка компилятор или статический анализатор показывает изменения только в слоях Infrastructure и UI.
  • Доменные события публикуются через порт, а не через конкретный транспорт.

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

Стоит ли полностью отказываться от фреймворка ради декаплинга?

Нет. Фреймворк закрывает полезные задачи на HTTP-слое и в инфраструктуре. Отказаться нужно не от инструмента, а от его проникновения в бизнес-логику. Контроллеры, DI-контейнер и адаптеры могут использовать фреймворк сколько угодно.

Как быстро можно внедрить декаплинг в существующий проект?

Постепенно, без остановки разработки. Начните с выделения самого ценного доменного кода и введения интерфейсов для его внешних зависимостей. Затем закрывайте адаптерами обращения к конкретным классам фреймворка. Полный переход для среднего проекта занимает от нескольких недель до пары месяцев.

Что делать, если бизнес-логика уже сильно связана с фреймворком?

Ищите seams — места, где можно вставить интерфейс. Сначала это могут быть простые обёртки над существующими вызовами. Затем заменяйте обёртки на собственные порты и адаптеры. Не пытайтесь переписать всё за одну итерацию: двигайтесь сервис за сервисом.

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

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

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

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

8 мин

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

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

7 мин

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

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

7 мин

Учимся по видеозаписям конференций PHP Frameworks Day: практический гид

Как системно учиться по записям выступлений с PHP-конференций: выбирать доклады, конспектировать код, внедрять практики в проект.

5 мин