PHPTime

Как настроить автодополнение 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
<?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
<?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).

PHP
// 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
<?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:

PHP
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() следующим методом:

PHP
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 и проверяет его во время выполнения.

Чек-лист для рабочего проекта

  1. Объявите фильтры публичными методами класса UserQuery с типизированными аргументами и возвращаемым типом static.
  2. В User::find() укажите тип UserQuery и создавайте запрос для static::class. Проверьте, какие условия добавляет общий базовый класс модели.
  3. Откройте User::find()-> в IDE и убедитесь, что редактор предлагает active() и byId(). Если методов нет, перейдите к объявлению find() и проверьте импорт класса User.
  4. Проверьте цепочку из двух scope на тестовых данных. Активная запись с нужным ID должна находиться, а неактивная запись с тем же ID — отсеиваться.
  5. Типизируйте геттеры нужных связей, затем проверьте автодополнение после вызова геттера. В запросах с 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 сужает тип до модели в нужной ветке.

Справка по теме

Ещё в разделе «Yii»

Расширения Yii 2: где искать и как устанавливать через Composer

Где искать расширения Yii 2, как проверить совместимость с PHP 8.3–8.5 и выбрать пакет. Установка через Composer, настройка и примеры популярных расширений.

7 мин

Yii 2 сегодня: установка, PHP 8.x и выбор фреймворка

Как установить Yii 2 на PHP 8.3–8.5, выбрать шаблон Basic или Advanced, проверить зависимости и решить, когда перейти на Yii 3 или Laravel.

6 мин

Миграция с Yii 1.1 на Yii 2: как перенести действующий проект

Как перенести проект с Yii 1.1 на Yii 2: пространства имён, ActiveRecord, формы, виджеты и конфигурация. План миграции с тестами и откатом.

7 мин

Yii 1.1.14 и хеширование паролей в PHP: от CPasswordHelper к Yii 2

Что Yii 1.1.14 изменил в работе с паролями и кешем. Как проверять bcrypt-хеши, мигрировать на password_hash или Yii 2 и настроить отдельный кеш в Redis.

7 мин