Декаплинг и фреймворки в 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 его реализует.
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 стороннего сервиса:
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 убирают эту зависимость.
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. Дальше работает типизированный объект:
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-совместимый пул становится проблемой. Вводится собственный порт:
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, он привязывается к конкретной библиотеке. Правильный подход — доменные события и порт для публикации:
declare(strict_types=1);
namespace App\Domain\Event;
final readonly class OrderPlaced
{
public function __construct(
public string $orderId,
public string $customerEmail,
) {}
}В Application объявляется интерфейс шины:
declare(strict_types=1);
namespace App\Application\Port;
interface EventBus
{
public function publish(object $event): void;
}Реализация в Infrastructure использует нужный транспорт: RabbitMQ, Kafka, SQS или синхронный вызов подписчиков, если асинхронность не требуется. При переходе на другой брокер меняется только класс-адаптер.
Конфигурация DI: где происходит подмена реализаций
Декаплинг становится практикой только тогда, когда DI-контейнер конфигурируется осознанно. Бизнес-логика не должна знать, какая реализация интерфейса используется в данный момент. Настройка связываний выносится в отдельный файл конфигурации:
// config/di.php
return [
OrderRepository::class => DoctrineOrderRepository::class,
Cache::class => RedisCache::class,
EventBus::class => RabbitMqEventBus::class,
];Если проект переезжает с одной реализации на другую, меняется одно значение в конфигурации, а не код в двадцати местах. Для тестов используется отдельная конфигурация с in-memory реализациями.
Стратегия перехода: декаплинг без остановки разработки
Никто не может позволить себе остановить продуктовую разработку ради рефакторинга на три месяца. Поэтому декаплинг внедряется постепенно:
- Выделите ядро: найдите сервисы с бизнес-правилами и перенесите их в отдельный слой без зависимостей от фреймворка.
- Введите порты для внешних зависимостей: репозитории, кэш, логирование, отправка почты, очередь.
- Создайте адаптеры поверх существующих классов фреймворка. На этом этапе бизнес-логика уже не импортирует вендора, но инфраструктура ещё использует старый код.
- Замените адаптеры на собственные реализации или на изоляцию через библиотеки, совместимые с PSR.
- Покройте переходные места тестами: интерфейсы позволяют проверять бизнес-правила без реальных баз и брокеров.
Когда большая часть ядра изолирована, смена фреймворка становится вопросом замены UI-слоя и адаптеров. Бизнес-логика остаётся прежней.
Чек-лист для проверки уровня декаплинга
- В папке
src/Domainнет ни одного импорта из сторонних библиотек, кроме PHP-расширений. - Application-сервисы получают зависимости через интерфейсы, объявленные в
Application\Port. - Контроллеры не передают HTTP-объекты в сервисы — только типизированные DTO.
- Каждый инфраструктурный сервис имеет собственный интерфейс-порт, даже если реализация использует готовый компонент фреймворка.
- Подмена реализации в тестах занимает меньше пяти минут: достаточно заменить класс в DI-конфиге.
- При поднятии мажорной версии фреймворка компилятор или статический анализатор показывает изменения только в слоях Infrastructure и UI.
- Доменные события публикуются через порт, а не через конкретный транспорт.
Частые вопросы
Стоит ли полностью отказываться от фреймворка ради декаплинга?
Нет. Фреймворк закрывает полезные задачи на HTTP-слое и в инфраструктуре. Отказаться нужно не от инструмента, а от его проникновения в бизнес-логику. Контроллеры, DI-контейнер и адаптеры могут использовать фреймворк сколько угодно.
Как быстро можно внедрить декаплинг в существующий проект?
Постепенно, без остановки разработки. Начните с выделения самого ценного доменного кода и введения интерфейсов для его внешних зависимостей. Затем закрывайте адаптерами обращения к конкретным классам фреймворка. Полный переход для среднего проекта занимает от нескольких недель до пары месяцев.
Что делать, если бизнес-логика уже сильно связана с фреймворком?
Ищите seams — места, где можно вставить интерфейс. Сначала это могут быть простые обёртки над существующими вызовами. Затем заменяйте обёртки на собственные порты и адаптеры. Не пытайтесь переписать всё за одну итерацию: двигайтесь сервис за сервисом.