#56688

#56688

• Реализовал возможность добавления кастомных полей фильтрации в Active Controller
• добавил доку и phpdoc на методы

4. Кастомные фильтры

Библиотека поддерживает добавление пользовательских полей фильтрации, которые не привязаны к атрибутам модели. Это позволяет создавать сложные фильтры с собственной логикой валидации и применения.

Настройка кастомных фильтров

Определите метод customFilters() в вашем контроллере:

namespace app\controllers;

use deck\ActiveController\ActiveController;
use app\models\Product;
use yii\db\ActiveQuery;

class ProductController extends ActiveController
{
    public $modelClass = Product::class;

    public function customFilters()
    {
        return [
            // Поиск по нескольким полям
            'search' => [
                'rules' => [
                    ['search', 'required'],
                    ['search', 'string', 'min' => 3, 'max' => 100],
                ],
                'label' => 'Поиск',
                'apply' => function(ActiveQuery $query, $value) {
                    $query->andWhere(['or',
                        ['ilike', 'name', $value],
                        ['ilike', 'description', $value]
                    ]);
                }
            ],
            
            // Фильтр по диапазону дат
            'date_range' => [
                'rules' => [
                    [['from', 'to'], 'required'],
                    [['from', 'to'], 'date', 'format' => 'php:Y-m-d'],
                ],
                'label' => 'Диапазон дат',
                'apply' => function(ActiveQuery $query, $value) {
                    $query->andWhere(['between', 'created_at', $value['from'], $value['to']]);
                }
            ],
            
            // Фильтр без валидации (опционально)
            'in_stock' => [
                'apply' => function(ActiveQuery $query, $value) {
                    if ($value === 'true') {
                        $query->andWhere(['>', 'stock_quantity', 0]);
                    }
                }
            ]
        ];
    }
}

Структура кастомного фильтра

Каждый фильтр может содержать:

• rules (опционально) - массив правил валидации в формате Yii2. Поддерживает все стандартные валидаторы и i18n.
• label (опционально) - метка атрибута для сообщений об ошибках.
• apply (обязательно) - функция применения фильтра к ActiveQuery. Получает объект запроса и значение фильтра.

Примеры использования

# Поиск по тексту
GET /products?filter[search]=laptop

# Фильтр по диапазону дат
GET /products?filter[date_range][from]=2024-01-01&filter[date_range][to]=2024-12-31

# Комбинация кастомных и стандартных фильтров
GET /products?filter[category_id]=5&filter[search]=laptop&filter[in_stock]=true

Обработка ошибок

При неудачной валидации API вернет ошибку 422:

   "error": {
      "name": "Unprocessable entity",
      "message": "Необрабатываемый экземпляр",
      "code": "031x00005",
      "status": 422,
      "type": "deck\\exceptions\\ValidationException",
      "fields": {
        "search2": [
          "Значение «Поиск» должно содержать минимум 3 символа."
        ]
      }
  },