laravel.pw

Русский

English

Русский

English

Оформление

Переход со spatie/laravel-query-builder ​

Коду, написанному для spatie/laravel-query-builder 7.x, 6.x или 5.x, нужна только смена неймспейса. Файл конфигурации остаётся как есть.

Шаги ​

  1. Замените пакет:

    bash
    composer remove spatie/laravel-query-builder
composer require myprogs/query-builder

  2. Посмотрите, что осталось изменить:

    bash
    php artisan query-builder:check-migration

    Команда только читает проект. Она перечисляет каждое упоминание Spatie\QueryBuilder\ в app, tests, routes, config и database с файлом, строкой и классом, который нужно использовать вместо него, и проверяет, что composer.json больше не требует пакет spatie. Она также предупреждает о том, что нужно проверить вручную:

    • установленные пакеты, которые сами требуют spatie/laravel-query-builder: они продолжают работать с классами spatie, а не с этим пакетом;
    • ключи опубликованного config/query-builder.php, которых этот пакет не знает;
    • внутренние трейты (Concerns\*), которые здесь ведут себя иначе;
    • то, на что опирается код для spatie 6 и чего пакет не сохраняет (см. ниже);
    • getEloquentBuilder() в классах, наследующих QueryBuilder, AllowedFilter или AllowedSort, и include() в классах, наследующих AllowedInclude (см. Отличия).

    Команда завершается с кодом 1, пока есть упоминания или пакет spatie указан в зависимостях, и с 0 в остальных случаях, поэтому её можно запускать в CI. --path=modules --path=src проверяет другие каталоги вместо каталогов по умолчанию.

  3. Замените неймспейс в коде, например в app/ и tests/:

    bash
    grep -rl 'Spatie\\QueryBuilder' app tests | xargs sed -i '' 's/Spatie\\QueryBuilder/MyProgs\\QueryBuilder/g'

    В Linux уберите '' после -i. Запустите проверку снова: блокеров быть не должно.

  4. Оставьте опубликованный config/query-builder.php как есть: имя файла и все ключи (parameters, delimiter, filter_value_splitting_enabled, suffixes, disable_invalid_*_query_exception, convert_*) совпадают.

  5. Если в baseline PHPStan упоминаются классы spatie, пересоздайте его: baseline хранит имена классов экранированными (Spatie\\\\QueryBuilder), и команда выше его не переписывает.

Всё, что проходит тестовый набор spatie/laravel-query-builder 7.3.6, продолжает работать. Отличия, которые можно заметить, перечислены в разделе Отличия от spatie.

Переход со spatie 6.x и более старых ​

Переходить сначала на spatie 7 не нужно. Помимо API 7.x пакет принимает:

  • массив вместо списка аргументов в allowedFilters([...]), allowedSorts([...]), allowedIncludes([...]), allowedFields([...]), defaultSort([...]) и defaultSorts([...]), причём массивы и коллекции среди элементов раскрываются на один уровень;
  • собственные фильтры, сортировки и include без возвращаемого типа void;
  • SortDirection::DESCENDING / SortDirection::ASCENDING и 'desc' / 'asc' в AllowedSort::defaultDirection();
  • AllowedFilter::beginsWithStrict() / endsWithStrict() (старые имена beginsWith() / endsWith());
  • разделитель последним аргументом фабрик фильтров (AllowedFilter::exact('id', null, true, '|')); он действует только на этот фильтр, как и ->delimiter('|');
  • ключи конфигурации count_suffix, exists_suffix и disable_invalid_includes_query_exception в опубликованном конфиге.

Не сохранены, и о них сообщает query-builder:check-migration:

  • статические сеттеры разделителя (QueryBuilderRequest::setArrayValueDelimiter() и подобные): это глобальное состояние; используйте ключ конфигурации delimiter;
  • методы коллекций у результата фабрики AllowedInclude;
  • разбиение значений по разделителю в QueryBuilderRequest::filters().

Что не поддерживается ​

  • Пакеты, которые сами указывают в типах классы Spatie\QueryBuilder\*. Им нужен адаптер или форк.
  • Код, расширяющий внутренние трейты spatie/laravel-query-builder.