К содержимому
Войти

PHP Road Map

🗂️ Слои приложения: MVC, сервисы и репозитории

Слои отвечают на один вопрос: где в проекте лежит правило «заказ нельзя оплатить дважды» и что придётся переписать, если поменяется база, платёжный шлюз или фреймворк. На собеседовании мидла по этой теме проверяют, писал ли человек что-то сложнее CRUD. Правильного ответа «всегда делай так» нет, есть цена каждого решения, и её надо уметь назвать

🧠 Как это устроено

MVC и где на самом деле бизнес-логика

MVC в веб-фреймворках делит код на три части: контроллер принимает запрос и возвращает ответ, модель работает с данными, представление рисует HTML или JSON. Про бизнес-логику MVC молчит, отдельного места для неё в схеме нет

Поэтому логика расползается в одну из двух сторон, и обе плохие:

  • Толстый контроллер. Метод store() на 200 строк валидирует, считает скидку, пишет в три таблицы, шлёт письмо и дёргает CRM. Тот же сценарий из консольной команды или очереди не вызвать без копипасты, а тест возможен только через HTTP с базой
  • Толстая модель. Логика переезжает в Eloquent-модель Order, и через год в ней 1500 строк: связи, скоупы, расчёт цены, уведомления, вызов платёжного API. Любой её метод тянет за собой базу

Выход — отделить то, что делает приложение, от того, как оно принимает запрос и хранит данные. Контроллер остаётся тонким: собрал вход, вызвал сценарий, вернул ответ

Слои по порядку

СлойЧто в нём лежитОт чего зависит
Presentation (HTTP, CLI, очередь)Контроллеры, консольные команды, обработчики сообщений, валидация формата запросаОт Application
ApplicationСценарии (use case, action), команды-DTO, транзакцииОт Domain и интерфейсов инфраструктуры
DomainСущности, value objects, интерфейсы репозиториев, доменные исключенияНи от чего, кроме PHP
InfrastructureРеализации репозиториев на Eloquent или Doctrine, HTTP-клиенты к чужим API, почта, кэшОт Domain (реализует его интерфейсы) и от библиотек

Главное правило — зависимости направлены внутрь: домен не знает про Laravel, Doctrine и Guzzle, а инфраструктура реализует его интерфейсы. Это инверсия зависимостей из SOLID. Как контейнер подставляет реализацию вместо интерфейса, разобрано на странице про DI и контейнер

Сервисный слой: use case и action-класс

Сценарий (use case, action, application service) — класс, который выполняет одно действие пользователя: «оформить заказ», «сменить тариф». Он получает вход, достаёт сущности через репозитории, вызывает методы домена и сохраняет результат. Правил он не содержит, они живут в сущностях и value objects

Частая форма — один публичный метод __invoke или handle, по классу на действие. Это лучше OrderService на 40 методов, конструктор которого принимает зависимости всех сорока

DTO и value object

Оба удобно писать как readonly-классы, но решают разные задачи

DTOValue object
ЗачемПеренести данные через границу: запрос → сценарий, сценарий → ответ, ответ чужого API → наш кодВыразить понятие предметной области: деньги, email, период
ПоведениеНет, только поляЕсть: add(), equals(), проверка в конструкторе
ИнвариантыОбычно нет, формат проверяет валидатор на входеОбъект в неверном состоянии создать нельзя
РавенствоНе важноПо значению: две суммы 1000 RUB равны
Где живётНа границах слоёвВнутри домена

DTO нужен, чтобы сценарий не принимал Request или массив $request->all(). В массиве ключ можно забыть, тип перепутать, и IDE не подскажет. DTO с типизированными полями — контракт, с которым сценарий вызывается из CLI так же, как из HTTP

Value object неизменяем: операция возвращает новый объект. У readonly-класса это делают «wither'ом» через clone, его разобрали на странице про современный PHP. Value object убирает целый класс ошибок: если Email проверяет формат в конструкторе, ни один метод дальше не получит невалидный адрес

Repository

Репозиторий — интерфейс доменного слоя, который выглядит как коллекция сущностей: get(OrderId $id): Order, save(Order $order), findUnpaidOlderThan(...). Интерфейс лежит в домене и говорит на языке домена, реализация лежит в инфраструктуре и знает про SQL. Сценарий зависит от интерфейса, и в тесте ему подсовывают реализацию в памяти

Репозиторий — не DAO на каждую таблицу. Метод findBy(array $criteria), который пробрасывает в ORM что угодно, делает его лишним слоем. В хорошем репозитории только те запросы, которые нужны сценариям, с именами по смыслу

Active Record против Data Mapper

Это два способа связать объект с таблицей, и на них построены два главных ORM в PHP

Active Record (Eloquent в Laravel): объект и есть строка таблицы. Модель наследует Illuminate\Database\Eloquent\Model, атрибуты читаются через магический __get, а сохраняет себя сама: $order->save(). Схема модели — это схема таблицы, полей в классе нет

Data Mapper (Doctrine ORM в Symfony): сущность — обычный класс с типизированными свойствами, который ничего не знает о базе. Отображение на таблицу описано атрибутами #[ORM\Entity] и #[ORM\Column], а читает и пишет отдельный объект EntityManager. Он держит Unit of Work: запоминает загруженные сущности, на flush() сравнивает их с исходным состоянием и одной транзакцией пишет все изменения. Подробно про persist, flush и Identity Map — на странице модуля Symfony про Doctrine

Active Record (Eloquent)Data Mapper (Doctrine)
Кто сохраняетСама модель: $model->save()EntityManager: persist() и flush()
Связь с базойМодель наследует базовый класс ORM, поля берутся из таблицыСущность — обычный класс, маппинг в атрибутах
Простой CRUDОчень быстро: модель, миграция, контроллерБольше кода: сущность, маппинг, репозиторий
Тест логики без базыТрудно: модель тянет соединение, статические Order::where() не подменитьЛегко: new Order(...) и вызов методов
Пакетные измененияКаждый save() — отдельный запросUnit of Work собирает изменения и пишет их на flush()
Подводные камниЛенивые связи и N+1, магия атрибутов не видна анализаторуПорог входа, прокси, неожиданные запросы на flush()

Про N+1 и жадную загрузку в Eloquent — на странице модуля Laravel. ORM обычно выбирает фреймворк, а на уровне проекта решают, пускать ли ORM-модель в домен или держать её за репозиторием

Внешний API за своим интерфейсом

Код, который ходит в платёжный шлюз, CRM или сервис доставки, прячут за интерфейсом с действием приложения: PaymentGateway::charge(), а не post('/v2/payments'). В тестах подставляется фейк без сети, а при смене провайдера пишется новый адаптер, и сценарии не меняются

Внутри адаптера нужен HTTP-клиент. PSR-18 описывает его интерфейс Psr\Http\Client\ClientInterface с одним методом sendRequest(RequestInterface): ResponseInterface. Его реализуют Guzzle и Psr18Client из Symfony HttpClient, так что адаптер можно писать против PSR-18 и не привязываться к библиотеке

Клиенты по-разному реагируют на ответы 4xx и 5xx, и это легко пропустить:

  • PSR-18 запрещает считать такой ответ ошибкой: клиент возвращает его как обычный, исключение бывает только при сетевой ошибке или некорректном запросе
  • Guzzle со своим методом request() по умолчанию бросает исключение (http_errors = true)
  • Symfony HttpClient бросает исключение при чтении тела или заголовков ответа со статусом 300–599, если до этого не вызвали getStatusCode()
  • Http в Laravel работает поверх Guzzle, но по умолчанию не бросает, ошибку включают вызовом throw()

Поэтому адаптер сам проверяет статус и переводит ответ провайдера в доменное исключение вроде PaymentDeclined, чтобы наружу не утекали ни исключения Guzzle, ни JSON чужого API

Лёгкий DDD без фанатизма

Из DDD в обычный PHP-проект стоит взять три понятия

  • Сущность — объект с постоянной идентичностью: заказ остаётся тем же заказом, когда меняется статус
  • Value object — объект без идентичности: сумма, адрес, диапазон дат
  • Агрегат — группа объектов, которую меняют только через корень. Заказ с его строками: строку нельзя добавить в обход Order::addLine(), потому что заказ проверяет, что он ещё не оплачен. Репозиторий заводят на корень агрегата, а не на каждую таблицу, и сохраняют агрегат целиком

Это оправдано, когда правил много, они меняются и стоят денег: биллинг, тарифы, склад. В админке с формами, где правило одно — «поле обязательно», агрегаты и репозитории утроят код, и Eloquent с form request будет лучшим решением

🛠️ На практике

Небольшой проект, разложенный по слоям. Папки называют по-разному, важно направление зависимостей:

src/
  Order/
    Domain/
      Order.php               # корень агрегата, правила
      OrderLine.php
      OrderRepository.php     # интерфейс
      PaymentGateway.php      # интерфейс
      Exception/PaymentDeclined.php
    Application/
      PlaceOrder.php          # сценарий
      PlaceOrderCommand.php   # DTO
    Infrastructure/
      DoctrineOrderRepository.php
      HttpPaymentGateway.php    # адаптер поверх PSR-18
    Http/
      PlaceOrderController.php
  Shared/
    Domain/Money.php
    Domain/Email.php

Value object на readonly-классе. Проверено на PHP 8.4:

<?php
declare(strict_types=1);

final readonly class Money
{
    public function __construct(
        public int $amount, // в копейках
        public string $currency,
    ) {
        if ($amount < 0) {
            throw new InvalidArgumentException('Сумма не может быть отрицательной');
        }
    }

    public function add(self $other): self
    {
        if ($other->currency !== $this->currency) {
            throw new LogicException('Разные валюты');
        }
        return new self($this->amount + $other->amount, $this->currency);
    }
}

$a = new Money(1000, 'RUB');
$b = $a->add(new Money(500, 'RUB'));
echo $a->amount, ' ', $b->amount, "\n";  // 1000 1500
var_dump($a == new Money(1000, 'RUB'));  // bool(true)
$a->amount = 5; // Error: Cannot modify readonly property Money::$amount

Для value object == уместно: он сравнивает класс и значения свойств. Сущности сравнивают по id

Сценарий получает DTO и зависит только от интерфейсов домена:

final readonly class PlaceOrderCommand
{
    public function __construct(
        public int $customerId,
        public array $items, // [productId => количество]
    ) {}
}

final class PlaceOrder
{
    public function __construct(
        private OrderRepository $orders,
        private ProductCatalog $catalog,
        private PaymentGateway $payments,
    ) {}

    public function __invoke(PlaceOrderCommand $cmd): string
    {
        $order = new Order($this->orders->nextId(), $cmd->customerId);
        foreach ($cmd->items as $productId => $qty) {
            $order->addLine($productId, $qty, $this->catalog->price($productId));
        }
        $this->orders->save($order);
        $this->payments->charge($cmd->customerId, $order->total());
        $order->markPaid();
        $this->orders->save($order);

        return $order->id;
    }
}

Контроллер сводится к трём строкам: собрать PlaceOrderCommand из провалидированного запроса, вызвать $placeOrder($command), вернуть JSON. Ту же команду собирает artisan-команда или обработчик очереди

PHP · Репозиторий в памяти и тест сценария без базы

final class InMemoryOrderRepository implements OrderRepository
{
    public array $saved = [];
    private int $seq = 0;

    public function nextId(): string
    {
        return 'ord-' . ++$this->seq;
    }

    public function save(Order $order): void
    {
        $this->saved[$order->id] = $order;
    }
}

final class FakePaymentGateway implements PaymentGateway
{
    public array $charges = [];

    public function charge(int $customerId, int $amount): string
    {
        $this->charges[] = $amount;
        return 'pay-1';
    }
}

// В тесте: два товара по 15 ₽ и один за 3 ₽
$repo = new InMemoryOrderRepository();
$pay = new FakePaymentGateway();
$catalog = new FixedPriceCatalog([10 => 1500, 20 => 300]);
$id = (new PlaceOrder($repo, $catalog, $pay))(new PlaceOrderCommand(7, [10 => 2, 20 => 1]));
// $repo->saved[$id]->status() === 'paid', $pay->charges === [3300]

Тест без базы и сети проверяет поведение: сколько списали и в каком состоянии заказ. DoctrineOrderRepository проверяет отдельный интеграционный тест с настоящей базой

PHP · Адаптер платёжного шлюза поверх PSR-18

use Psr\Http\Client\ClientInterface;
use Psr\Http\Message\RequestFactoryInterface;
use Psr\Http\Message\StreamFactoryInterface;

final class HttpPaymentGateway implements PaymentGateway
{
    public function __construct(
        private ClientInterface $http,
        private RequestFactoryInterface $requests,
        private StreamFactoryInterface $streams,
        private string $baseUrl,
    ) {}

    public function charge(int $customerId, int $amount): string
    {
        $body = json_encode(['customer' => $customerId, 'amount' => $amount], JSON_THROW_ON_ERROR);
        $request = $this->requests->createRequest('POST', $this->baseUrl . '/payments')
            ->withHeader('Content-Type', 'application/json')
            ->withBody($this->streams->createStream($body));

        $response = $this->http->sendRequest($request);
        // PSR-18 не бросает на 4xx и 5xx: статус проверяет адаптер
        if ($response->getStatusCode() >= 400) {
            throw new PaymentDeclined($response->getStatusCode());
        }

        return json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR)['id'];
    }
}

Вместо ClientInterface контейнер подставит Guzzle или Psr18Client из Symfony HttpClient. В тестах адаптера пригодятся MockHandler из Guzzle, MockHttpClient из Symfony или Http::fake() в Laravel, если адаптер написан на фасаде Http

⚠️ Где ошибаются

  • Request в сценарии. Сценарий принимает Illuminate\Http\Request, и вызвать его из очереди уже нельзя: там нет запроса. Вход сценария — DTO, собирает его контроллер
  • Репозиторий, который возвращает Eloquent-модель. Интерфейс объявлен, но get() отдаёт Order extends Model, и снаружи вызывают $order->save() и ленивые связи. Слой есть, изоляции нет. Либо честно работают с моделью без репозитория, либо репозиторий отдаёт доменный объект
  • Анемичная модель. Сущность — набор геттеров и сеттеров, а проверка «заказ уже оплачен» живёт в сервисе. Второй сервис её забывает, и заказ оплачивают дважды. Правило, которое защищает состояние, пишут в методе самого объекта
  • Внешний вызов внутри транзакции базы. Сценарий открывает транзакцию, зовёт платёжный API и ждёт ответа 10 секунд, а строки заказа всё это время заблокированы. Если шлюз ответил успехом, а COMMIT упал, деньги списаны без заказа. Правильно сохранить заказ в статусе «ожидает оплаты», заплатить вне транзакции с идемпотентным ключом и затем отметить оплату
  • Слои ради слоёв. Интерфейс на каждый класс и маппер между четырьмя одинаковыми объектами в проекте из трёх форм. Слой окупается, когда за ним правило, которое надо тестировать, или зависимость, которую надо подменять

🎯 Вопросы с собеседований

MVC: где держать бизнес-логику? Чем плохи толстый контроллер и толстая модель?

MVC в веб-фреймворках говорит, кто принимает запрос, кто хранит данные и кто рисует ответ, но отдельного места для бизнес-правил в нём нет. В толстом контроллере логику не вызвать из консоли или очереди и не протестировать без HTTP. В толстой Eloquent-модели правила смешаны с хранением и внешними вызовами, класс растёт до тысяч строк, а любой тест тянет базу. Я держу контроллер тонким, сценарий выношу в action-класс, а правила, которые защищают состояние, кладу в методы сущности. Для простого CRUD хватает модели и form request

Зачем нужны Repository, DTO и сервисный слой?

Сервисный слой, то есть сценарии, описывает, что делает приложение, и вызывается одинаково из HTTP, CLI и очереди. DTO переносит данные через границу слоя с типами вместо массива, поэтому у сценария есть явный контракт. Репозиторий — интерфейс домена, похожий на коллекцию сущностей, а его реализация на ORM лежит в инфраструктуре. Вместе они дают тест сценария без базы и сети и позволяют менять хранение и внешние сервисы, не трогая логику

Чем Active Record отличается от Data Mapper?

В Active Record объект и есть строка таблицы: модель Eloquent наследует базовый класс ORM и сохраняет себя через save(). Это быстро для CRUD, но логику в модели трудно тестировать без базы. В Data Mapper сущность — обычный PHP-класс, а сохраняет её отдельный EntityManager в Doctrine, отображение описано атрибутами. Unit of Work отслеживает изменения загруженных сущностей и пишет их одной транзакцией на flush(). Платят порогом входа и объёмом кода, выигрывают чистым доменом и тестами без базы

Нужен ли репозиторий поверх Eloquent?

Зависит от того, что за ним. Если репозиторий возвращает ту же Eloquent-модель, а снаружи на ней вызывают save() и связи, он ничего не изолирует и только добавляет файл, лучше честно работать с моделью и скоупами. Репозиторий окупается, когда доменные объекты отделены от модели или сложные запросы хочется собрать в одном месте с понятными именами. В типичном Laravel-проекте тесты гоняют с базой через RefreshDatabase, и это нормально

Чем DTO отличается от value object?

DTO — контейнер данных для передачи через границу: у него нет поведения и обычно нет инвариантов, формат проверяет валидатор до него. Value object — понятие предметной области вроде денег или email: он проверяет себя в конструкторе, неизменяем, сравнивается по значению и умеет операции вроде add(). Оба удобно писать readonly-классами, но DTO живёт на границах слоёв, а value object внутри домена

Как изолировать интеграцию со сторонним API?

Объявляю интерфейс на языке приложения, например PaymentGateway::charge(), и пишу адаптер в инфраструктуре. Внутри адаптера HTTP-клиент, лучше через PSR-18 ClientInterface, чтобы подставить Guzzle или Symfony HttpClient. Адаптер сам проверяет статус, потому что PSR-18 и Http в Laravel не бросают на 4xx и 5xx, и переводит ответ в доменные исключения. В тестах сценария подставляю фейк интерфейса, а адаптер проверяю моком HTTP-клиента

Что такое агрегат и когда DDD не нужен?

Агрегат — группа сущностей и value objects, которую меняют только через корень: строки заказа добавляют через Order::addLine(), и корень проверяет правила вроде «оплаченный заказ не меняется». Репозиторий заводят на корень и сохраняют агрегат целиком, другие агрегаты ссылаются на него по id. DDD окупается в биллинге, тарифах, на складе, а в админке и простом CRUD только утроит код

📚 Что почитать