Введение
Обёртка пересылает вызовы вложенному объекту через __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), здесь не проверялось.
Шпаргалка
@mixin Делегатставится над классом-обёрткой с__call.- Явный список методов или статические синтетические методы —
@method. - Собственный метод обёртки перекрывает метод делегата.
- Fluent-методы с
staticвозвращают тип делегата — для цепочек метод объявляется в обёртке. - Общий интерфейс надёжнее тега: он проверяется при выполнении.
Итог
@mixin — одна строка, которая переносит методы делегата в типы обёртки и включает в PHPStan проверку сигнатур. Для явного списка подходит @method, для жёсткой гарантии — интерфейс. Все выводы статьи подтверждены только на PHPStan: поведение PhpStorm требует отдельной проверки.