@mixin в PHPDoc: подсказки IDE для __call и обёрток в PHP

@mixin в PHPDoc: подсказки IDE для __call и обёрток в PHP
содержание

Введение

Обёртка пересылает вызовы вложенному объекту через __call, и в рантайме всё работает. Но статический анализатор останавливается на первом же вызове: Call to an undefined method LoggedMailer::send(). Метода send() в классе действительно нет, есть только магия. Так ведут себя декораторы, прокси и любая реализация паттерна «Делегирование» на PHP.

Лечится это одной строкой PHPDoc — тегом @mixin. Далее разбирается, что он обещает анализатору, как применяется к обёрткам, чем отличается от @method, где его использует Laravel и на чём он перестаёт помогать. Все результаты получены на PHPStan 2.2.16 (PHP 8.5.9, Docker-образ ghcr.io/phpstan/phpstan). Поведение PhpStorm не проверялось: проверено только PHPStan, выводов об IDE в статье нет.

Что такое @mixin

Тег @mixin ИмяКласса пишется над классом и заявляет: методы и свойства указанного класса доступны и у этого. В стандарт PHPDoc тег не входит и в документации phpDocumentor не описан, зато его понимают инструменты — PHPStan и Psalm (по их документации). С точки зрения PHPStan, @mixin помечает класс, который пересылает неизвестные вызовы и обращения к свойствам дальше — через __call и __get/__set.

/**
 * @mixin Mailer
 */
final class LoggedMailer
{
    public function __construct(private Mailer $mailer)
    {
    }

    public function __call(string $name, array $arguments): mixed
    {
        error_log("mailer: {$name}");

        return $this->mailer->$name(...$arguments);
    }
}

Пример 1: обёртка с __call

Сквозной пример: сервис Mailer и обёртку LoggedMailer, которая пишет в лог каждый вызов. Без тега анализатор на уровне 5 отвергает любой делегированный метод.

final class Mailer
{
    public function send(string $to, string $subject): bool
    {
        return true;
    }

    public function to(string $address): static
    {
        return $this;
    }
}

function notify(LoggedMailer $mailer): bool
{
    return $mailer->send('user@example.com', 'Заказ оформлен');
}
Состояние Результат PHPStan, уровень 5
Без @mixin Call to an undefined method LoggedMailer::send().
С @mixin Mailer ошибок нет, тип $mailer->send(...) — bool
С @mixin Mailer, вызов send(1, 'Hi') Parameter #1 $to of method Mailer::send() expects string, int given.

Кроме самих подсказок, тег даёт и проверку сигнатур: аргументы вызова сверяются с объявлением Mailer::send(), как будто метод есть у обёртки.

Пример 2: декоратор и цепочка вызовов

Для CachedRepository вокруг Repository схема та же: над декоратором достаточно поставить @mixin Repository. Типы возврата PHPStan берёт у делегата, и здесь скрыта ловушка для цепочек. Метод to() объявлен как static, а dumpType($wrapper->to('a@b.c')) показывает Mailer, не LoggedMailer. Анализатор не знает, что обёртка возвращает саму себя, поэтому после первого fluent-вызова логирующая обёртка пропадает из типов. Если цепочки нужны, метод лучше объявить в самой обёртке с возвратом static.

@mixin или @method

Разница в подходе: @method перечисляет методы явно, а @mixin подтягивает всё, что есть у класса.

Критерий @mixin Класс @method
Что описывает все публичные члены класса только перечисленные методы
Сигнатуры берутся из класса пишутся вручную
Синхронность с кодом автоматически легко устаревает
Ограничение набора нет да
Статические методы @method static не нужен (см. ниже) @method static

На PHPStan проверено: @method bool send(string $to, string $subject) и @method static Mailer fake() дают тот же результат для send() и fake(). Правило выбора простое. @method нужен, когда наружу должен смотреть явный список или синтетические методы, которых у делегата нет. @mixin подходит, когда обёртка пересылает «всё подряд». Надёжнее обоих вариантов общий интерфейс или наследование: методы тогда настоящие, а не заявленные в комментарии.

Как это использует Laravel

В vendor/ Laravel 13.30.1 тег @mixin стоит на классах, которые пересылают вызовы через __call:

/**
 * @mixin \Illuminate\Cache\Repository
 * @mixin \Illuminate\Contracts\Cache\LockProvider
 */
class CacheManager implements FactoryContract
{
    public function __call($method, $parameters)
    {
        return $this->store()->$method(...$parameters);
    }
}

Та же разметка у LogManager (@mixin \Illuminate\Log\Logger), DatabaseManager (@mixin \Illuminate\Database\Connection), Mail\Message (@mixin \Symfony\Component\Mime\Email) и Eloquent\Builder (@mixin \Illuminate\Database\Query\Builder). Есть @mixin \DummyTarget и в шаблоне facade.stub. Как видно на CacheManager, тегов у одного класса может быть несколько. Для моделей похожие аннотации обычно создаёт Laravel IDE Helper.

Ограничения и подводные камни

Если не сказано иначе, результаты ниже получены на PHPStan 2.2.16, уровень 5.

  • Реальные методы приоритетнее. Если в обёртке объявлен name(): int, а у делегата name(): string, тип будет int.
  • Приватные и защищённые методы недоступны. Вызов build() (protected) даёт Call to protected method build() of class Mailer., log() (private) — аналогичную ошибку.
  • Статические вызовы разрешаются. NoStatic::make() при @mixin Repo даёт тип Repo даже без __callStatic. Это лишь подсказка для анализатора: при выполнении без __callStatic вызов упадёт.
  • Реальную работу __call тег не проверяет. PHPStan не убеждается, что магия существует: @mixin сработал и у класса вообще без __call.
  • Неизвестные методы по-прежнему ошибка: $wrapper->nothing() даёт Call to an undefined method.
  • Дженерики работают. @template T of object + @mixin T для new Proxy(new Repo()) выводит Proxy<Repo>, а find() возвращает string|null. Для «голого» Proxy без уточнения типа шаблона метод не находится.
  • Psalm (по его документации): цепочки прослеживаются через негенерические mixin, а generic-mixin вроде @mixin Collection<T> не разворачиваются.
  • Начиная с уровня 6 появятся замечания к самому __call: у $arguments нужно указать тип значений, например array<int, mixed>.

Проверка

Убедиться, что тег сработал, проще всего через dumpType() и запуск анализа в Docker:

docker run --rm -v "$PWD:/app" ghcr.io/phpstan/phpstan analyse -l 5 --no-progress src
\PHPStan\dumpType($mailer->send('user@example.com', 'Тема'));
// Dumped type: bool

Без @mixin вместо типа выведется Call to an undefined method. Как ведёт себя подсказка в PhpStorm (Ctrl+Q), здесь не проверялось.

Шпаргалка

  1. @mixin Делегат ставится над классом-обёрткой с __call.
  2. Явный список методов или статические синтетические методы — @method.
  3. Собственный метод обёртки перекрывает метод делегата.
  4. Fluent-методы с static возвращают тип делегата — для цепочек метод объявляется в обёртке.
  5. Общий интерфейс надёжнее тега: он проверяется при выполнении.

Итог

@mixin — одна строка, которая переносит методы делегата в типы обёртки и включает в PHPStan проверку сигнатур. Для явного списка подходит @method, для жёсткой гарантии — интерфейс. Все выводы статьи подтверждены только на PHPStan: поведение PhpStorm требует отдельной проверки.

Похожие