Как настроить автодополнение scope-методов ActiveRecord в Yii2
Если IDE не предлагает scope после User::find(), проверьте, какой тип возвращает этот метод. В Yii2 достаточно вынести фильтры в отдельный класс ActiveQuery и указать его как возвращаемый тип find(). Те же фильтры можно использовать в связях hasOne() и hasMany().
Почему IDE не видит scope после find()
Scope в Yii2 — именованный метод, который добавляет к запросу условие, сортировку или другую часть SQL. Например, active() ограничивает выборку активными пользователями, а byId() добавляет условие по первичному ключу. Scope возвращает объект запроса, поэтому фильтры можно комбинировать в одной цепочке.
IDE определяет доступные методы по типу выражения слева от ->. Если User::find() объявлен как возвращающий базовый ActiveQuery, редактор видит where(), orderBy() и one(), но не знает о методах из UserQuery. Для автодополнения нужны обе части: объект UserQuery во время выполнения и тот же тип в объявлении User::find().
Создайте класс UserQuery с фильтрами
Пример рассчитан на PHP 8.3–8.5. В приложении с пространством имён app поместите классы UserQuery, User и Post из примеров в отдельные файлы каталога models. Предполагается, что у таблицы user есть колонки id и status, а у таблицы post — author_id и editor_id. В примере статус 1 означает активного пользователя.
<?php
declare(strict_types=1);
namespace app\models;
use yii\db\ActiveQuery;
class UserQuery extends ActiveQuery
{
public function byId(int $id): static
{
// Дополняем условия, уже заданные в запросе.
return $this->andWhere(['id' => $id]);
}
public function active(): static
{
return $this->andWhere(['status' => User::STATUS_ACTIVE]);
}
}Тип static сохраняет конкретный класс запроса при наследовании. Если позже появится подкласс UserQuery, IDE сможет предлагать его методы и после вызова унаследованного scope. Тип int задаёт контракт для идентификатора. Значение из HTTP-запроса следует валидировать на входе, поскольку оно часто приходит строкой. Строгий режим для аргументов скалярных типов определяется файлом, из которого вызывают метод.
Используйте andWhere() для фильтров, которые должны сочетаться друг с другом. Повторный вызов where() заменяет ранее заданное условие. Если scope вызывает where(), он может незаметно сбросить фильтр по организации, статусу или другому полю, добавленный вызывающим кодом. Массив условий Yii2 избавляет от ручной подстановки значений в SQL.
Верните UserQuery из User::find()
<?php
declare(strict_types=1);
namespace app\models;
use yii\db\ActiveRecord;
class User extends ActiveRecord
{
public const int STATUS_ACTIVE = 1;
public static function tableName(): string
{
return '{{%user}}';
}
public static function find(): UserQuery
{
// Запрос будет создавать экземпляры вызванного класса модели.
return new UserQuery(static::class);
}
}В Yii2 find() возвращает запрос. Идентификатор передают в byId(), а выборку выполняют через one(). Если нужен только поиск по первичному ключу без дополнительных условий, подойдёт User::findOne($id).
// IDE предлагает оба scope и показывает их параметры.
$user = User::find()->active()->byId(42)->one();
if ($user instanceof User) {
// Здесь редактор видит свойства и методы модели User.
echo $user->getPrimaryKey();
}В старом проекте метод find() иногда унаследован от собственного базового ActiveRecord. Перед переопределением проверьте его сигнатуру и логику. Например, если базовый метод уже добавляет фильтр по организации, прямое создание UserQuery в обход этой логики уберёт фильтр. Сохраните общую настройку запроса и используйте совместимый возвращаемый тип.
Типизируйте связи hasOne и hasMany
При создании связи Yii2 получает запрос через find() целевой модели. Поэтому связь на User использует UserQuery, а hasOne() и hasMany() дополнительно настраивают привязку и кратность. Базовые методы объявляют общий тип запроса, поэтому для конкретного возвращаемого типа покажите PHP и IDE, какой объект пришёл из фреймворка.
<?php
declare(strict_types=1);
namespace app\models;
use LogicException;
use yii\db\ActiveRecord;
class Post extends ActiveRecord
{
public static function tableName(): string
{
return '{{%post}}';
}
public function getAuthor(): UserQuery
{
$query = $this->hasOne(User::class, ['id' => 'author_id']);
if (!$query instanceof UserQuery) {
throw new LogicException('Связь author ожидает UserQuery.');
}
return $query;
}
public function getActiveEditedPosts(): \yii\db\ActiveQuery
{
// Связь с постами не нужна для фильтрации пользователей.
return $this->hasMany(self::class, ['editor_id' => 'author_id']);
}
}Для связи hasMany() с пользователями подход тот же. Например, в модели Team с первичным ключом id и колонкой team_id у пользователей геттер может сразу применить scope:
public function getActiveMembers(): UserQuery
{
$query = $this->hasMany(User::class, ['team_id' => 'id']);
if (!$query instanceof UserQuery) {
throw new \LogicException('Связь activeMembers ожидает UserQuery.');
}
return $query->active();
}В массиве привязки ключ относится к целевой таблице, значение — к текущей модели. Вызов $post->getAuthor()->active()->one() выполняет запрос с дополнительным фильтром. Свойство $post->author возвращает результат связи, то есть модель или null. Для связи hasMany() свойство возвращает массив. Если IDE не распознаёт магические свойства Yii2, опишите их в PHPDoc модели через @property-read User|null $author или @property-read User[] $activeMembers.
Что учесть при JOIN и asArray()
Квалифицируйте колонки при соединении таблиц
В простом запросе условие по id однозначно. После JOIN обе таблицы могут содержать одноимённый столбец. Если scope часто используется в таких запросах, можно добавить параметр для псевдонима основной таблицы. Например, замените byId() следующим методом:
public function byId(int $id, ?string $alias = null): static
{
$column = $alias === null ? 'id' : $alias . '.id';
return $this->andWhere([$column => $id]);
}В цепочке User::find()->alias('u')->byId(42, 'u') фильтр применяется к u.id. Псевдоним задавайте в коде приложения. Параметры запроса пользователя подходят для значений условий после валидации. Имена таблиц и колонок должны оставаться под контролем приложения.
Различайте тип запроса и тип результата
Сигнатура find(): UserQuery описывает объект запроса. В обычном режиме one() возвращает модель или null, а после asArray() — массив или null. Метод all() возвращает массив моделей или массив строк, представленных массивами. Общее объявление методов Yii2 учитывает эти режимы, поэтому автодополнение после one() может быть менее точным, чем после find(). В коде, которому нужна модель, проверка instanceof User одновременно уточняет тип для IDE и проверяет его во время выполнения.
Чек-лист для рабочего проекта
- Объявите фильтры публичными методами класса
UserQueryс типизированными аргументами и возвращаемым типомstatic. - В
User::find()укажите типUserQueryи создавайте запрос дляstatic::class. Проверьте, какие условия добавляет общий базовый класс модели. - Откройте
User::find()->в IDE и убедитесь, что редактор предлагаетactive()иbyId(). Если методов нет, перейдите к объявлениюfind()и проверьте импорт классаUser. - Проверьте цепочку из двух scope на тестовых данных. Активная запись с нужным ID должна находиться, а неактивная запись с тем же ID — отсеиваться.
- Типизируйте геттеры нужных связей, затем проверьте автодополнение после вызова геттера. В запросах с
JOINпроверьте условия по одноимённым колонкам.
Частые вопросы
Нужна ли аннотация @method, чтобы PhpStorm видел scope Yii2?
Для публичного метода класса UserQuery достаточно объявить User::find() с возвращаемым типом UserQuery. IDE прочитает сигнатуру самого метода и покажет его параметры.
Можно ли использовать scope в связях hasOne() и hasMany()?
Да. Yii2 создаёт запрос связи через find() целевой модели. Если он возвращает UserQuery, вызовите scope внутри геттера или верните UserQuery из геттера, чтобы редактор предлагал фильтры вызывающему коду.
Почему PhpStorm видит active(), а после one() не предлагает свойства User?
Метод active() сохраняет тип UserQuery, а one() выполняет запрос и может вернуть модель, массив после asArray() или null. Проверка instanceof User сужает тип до модели в нужной ветке.