PHPTime

Поиск и сортировка связанных моделей в CGridView

В таблице публикаций удобно показывать имя автора, искать по его части и сортировать строки по алфавиту. В Yii 1.1 для этого нужно связать фильтр CGridView с атрибутом модели, а в CActiveDataProvider задать условия поиска и сортировки по присоединённой таблице.

Связь Post с Author и поле фильтра

В примере у публикации есть первичный ключ id, заголовок title и внешний ключ id_author. Он ссылается на Author.id, а в таблице нужно показывать Author.username. Связь BELONGS_TO даёт каждой публикации не более одного автора, поэтому присоединение сохраняет одну строку на публикацию.

Добавьте в существующую модель Post открытое свойство author_search и связь author. В примере у связи явно задан SQL-псевдоним author. Это имя будет использоваться в условиях и сортировке.

PHP
public string $author_search = '';

public function relations()
{
    return [
        'author' => [self::BELONGS_TO, 'Author', 'id_author', 'alias' => 'author'],
    ];
}

Если в relations() уже есть другие связи, добавьте новый элемент в существующий массив. Свойство author_search хранит текст фильтра и не требует столбца в базе. В примере контроллер присваивает его напрямую после проверки типа. При массовом присваивании через $model->attributes или setAttributes() добавьте ['author_search', 'safe', 'on' => 'search'] в существующие правила и предварительно проверьте, что значение является строкой. Правило safe разрешает присваивание, а проверку типа нужно выполнить отдельно.

Как принять фильтр из запроса

CGridView отправляет значение поля в параметре Post[author_search]. В действии списка создайте модель в сценарии search, сбросьте значения атрибутов БД, затем загрузите фильтр. Проверка типа также обработает запрос, в котором вместо строки передан массив.

PHP
public function actionAdmin(): void
{
    $model = new Post('search');
    $model->unsetAttributes();

    $filters = Yii::app()->request->getQuery('Post', []);
    $authorSearch = is_array($filters) ? ($filters['author_search'] ?? '') : '';
    // Принимаем только строку, в том числе строку «0».
    $model->author_search = is_string($authorSearch) ? trim($authorSearch) : '';

    $this->render('admin', ['model' => $model]);
}

В файле модели или контроллера можно включить declare(strict_types=1); сразу после открывающего PHP-тега. В приложениях под PHP 8.3–8.5 проверяйте совместимость установленной сборки Yii 1.1 и расширений с каждой версией PHP, которую используете. При обновлении сохраняйте совместимые сигнатуры переопределённых методов фреймворка.

Фильтрация по имени автора через CDbCriteria

В Post::search() явно подключите связь через with. Параметр together оставляет присоединение в запросе выборки публикаций, где имя автора нужно для WHERE и ORDER BY. Предварительная загрузка связи также позволяет вывести авторов без отдельного запроса для каждой строки.

PHP
public function search(): CActiveDataProvider
{
    $criteria = new CDbCriteria();
    $criteria->alias = 't';
    $criteria->with = [
        'author' => ['joinType' => 'LEFT JOIN'],
    ];
    $criteria->together = true;
    // Третий аргумент включает поиск вхождения через LIKE.
    $criteria->compare('author.username', $this->author_search, true);

    return new CActiveDataProvider($this, [
        'criteria' => $criteria,
        'sort' => [
            'defaultOrder' => 't.id DESC',
            'attributes' => [
                'author_search' => [
                    'asc' => 'author.username ASC, t.id ASC',
                    'desc' => 'author.username DESC, t.id DESC',
                ],
                'title' => [
                    'asc' => 't.title ASC, t.id ASC',
                    'desc' => 't.title DESC, t.id DESC',
                ],
            ],
        ],
    ]);
}

При пустой строке compare() пропускает условие. При вводе, например, иван поиск соответствует шаблону %иван%. Yii передаёт значение как связанный параметр и по умолчанию экранирует специальные символы шаблона % и _. Чувствительность к регистру и правила сравнения кириллицы зависят от СУБД и настроек сравнения строк. Проверьте на своей базе, должны ли одинаково находиться «Иван» и «иван».

С LEFT JOIN публикация без автора остаётся в списке при пустом фильтре. Когда задана подстрока, условие по author.username исключает такую публикацию, поскольку её имя автора равно NULL. Пагинация может выполнять отдельный запрос подсчёта. Важно, чтобы число строк в пагинаторе соответствовало тому же фильтру.

Сортировка по имени и стабильные страницы

Ключ author_search в sort.attributes совпадает с именем колонки CGridView. По нажатию на заголовок CSort выбирает одно из двух заданных выражений. SQL-поля и направления сортировки заданы в коде, поэтому текст фильтра и произвольные значения из запроса не попадают в ORDER BY.

Второй ключ t.id задаёт однозначный порядок публикаций с одинаковым именем автора. При неизменных данных это удерживает строки на своих страницах между запросами. Место строк с NULL при сортировке зависит от СУБД и направления. Если по требованиям публикации без автора должны всегда идти в конце, добавьте первым ключом в оба выражения сортировки CASE WHEN author.username IS NULL THEN 1 ELSE 0 END ASC.

В примере список разрешённых полей задан явно. Если экран уже поддерживает сортировку по другим колонкам, сохраните их в этом списке. В Yii 1.1 элемент '*' включает стандартную сортировку по атрибутам модели. При соединении таблиц явное указание псевдонимов особенно полезно для общих имён столбцов, таких как id.

Колонка автора в CGridView

В представлении admin используйте ту же модель для dataProvider и filter. Параметр name связывает колонку с полем ввода и конфигурацией сортировки, а value берёт текст для конкретной строки из связанной модели.

PHP
$this->widget('zii.widgets.grid.CGridView', [
    'id' => 'post-grid',
    'dataProvider' => $model->search(),
    'filter' => $model,
    'columns' => [
        'title',
        [
            'name' => 'author_search',
            'header' => 'Автор',
            'type' => 'text',
            'value' => static function (Post $data): string {
                // Пустая связь возможна при LEFT JOIN.
                return (string) ($data->author?->username ?? '—');
            },
        ],
    ],
]);

Тип text экранирует значение при выводе. Если поле под заголовком появилось, но заголовок не переключает сортировку, проверьте совпадение name с ключом в sort.attributes. При ошибке unknown column сравните псевдоним в SQL с тем, что записан в compare(), asc и desc.

Когда JOIN меняет число строк

Для связи BELONGS_TO этот подход сохраняет размер страницы, если соединение идёт по уникальному ключу автора. У HAS_MANY прямой JOIN может дать несколько SQL-строк на одну публикацию. Даже если Active Record соберёт их в один объект, SQL уже мог применить LIMIT к размноженным строкам. Тогда на странице окажется меньше публикаций, чем ожидается.

Для фильтра «есть хотя бы одна связанная запись с таким именем» используйте EXISTS с параметром. Для сортировки по коллекции сначала определите, какое значение представляет публикацию, например минимальное имя связанного участника. Вычислите это значение в подзапросе с группировкой по идентификатору публикации и присоедините результат, содержащий максимум одну строку на публикацию.

Если фильтр замедлился на большом списке, посмотрите план запросов выборки и подсчёта с реальной подстрокой. Начальный % в LIKE '%текст%' обычно мешает использовать обычный B-tree для поиска по имени. Если по требованиям подходит поиск по началу имени, проверьте префиксный шаблон и его план. Если нужно искать именно внутри имени, выбирайте индекс под поиск подстроки с учётом возможностей вашей СУБД.

Чек-лист перед выпуском

  • Пустой фильтр показывает все публикации, а часть имени находит только подходящих авторов.
  • Строка 0 сохраняется как фильтр, массив во входном параметре не вызывает ошибку, а % и _ ищутся как обычные символы.
  • Заголовок «Автор» сортирует в обе стороны. При одинаковых именах и неизменных данных публикации сохраняют порядок при переходе между страницами.
  • Публикация без автора выводится с прочерком при пустом фильтре и исчезает при поиске по имени.
  • Число результатов в пагинаторе совпадает с отфильтрованным списком, а при выводе колонки не появляется отдельный запрос на каждую публикацию.

Частые вопросы

Можно ли фильтровать по имени автора без нового столбца в таблице Post?

Да. Добавьте в Post открытое свойство author_search для текста фильтра. Условие поиска обращается к author.username в присоединённой таблице.

Почему имя автора отображается, но колонка не сортируется?

Отображение работает через value. Для сортировки имя колонки должно совпадать с ключом в sort.attributes, а выражения asc и desc должны ссылаться на псевдоним присоединённой таблицы.

Почему при фильтрации по связи HAS_MANY на странице меньше строк, чем задано?

JOIN может создать несколько SQL-строк для одной публикации, и LIMIT применяется до сборки моделей. Для проверки наличия связанной записи используйте EXISTS, а для сортировки вычисляйте одно значение на публикацию.

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

Ещё в разделе «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 мин

Как настроить автодополнение scope-методов ActiveRecord в Yii2

Настройте автодополнение scope-методов Yii2 в PhpStorm: создайте класс ActiveQuery, типизируйте find() и используйте фильтры в связях hasOne и hasMany.

7 мин