Руководство по обновлению

Изменения, оказывающие большое влияние

• Обновление зависимостей
• Обновление минимальной стабильности

Изменения со средней степенью воздействия

• Выражения базы данных
• Свойство “Dates” модели
• Monolog 3
• Теги кэша Redis
• Сервис Mocking
• Каталог языка

Изменения с низким уровнем воздействия

• Сообщения правила валидации на основе замыкания
• Метод after запроса формы
• Привязка публичного пути
• Конструктор исключения запроса
• Возвращаемое значение Rate Limiter
• Метод Redirect::home
• МетодBus::dispatchNow
• МетодregisterPolicies
• ULID столбцы

Обновление с 9.x версии до 10.0

Приблизительное время обновления: 10 минут

Мы стараемся задокументировать каждое возможное изменение, которое может привести к нарушению совместимости. Поскольку некоторые из этих критических изменений находятся в малоизвестных частях фреймворка, только часть этих изменений может повлиять на ваше приложение. Хотите сэкономить время? Вы можете использовать Laravel Shift , чтобы автоматизировать процесс обновления вашего приложения.

Обновление зависимостей

Вероятность воздействия: высокая

Требуется PHP 8.1.0

Laravel теперь требует PHP версии 8.1.0 или выше.

Требуется Composer 2.2.0

Laravel теперь требует Composer 2.2.0 или выше.

Зависимости Composer

Обновите следующие зависимости в вашем файле composer.json:

• laravel/framework до ^10.0
• laravel/sanctum до ^3.2
• doctrine/dbal до ^3.0
• spatie/laravel-ignition до ^2.0
• laravel/passport до ^11.0 (Руководство по обновлению)
• laravel/ui to ^4.0

Если вы обновляете Sanctum с 2.x до 3.x из релиза 2.x, пожалуйста, ознакомьтесь с руководством по обновлению Sanctum.

Кроме того, если вы хотите использовать PHPUnit 10, вам следует удалить атрибут processUncoveredFiles из раздела <coverage> файла phpunit.xml. Затем обновите следующие зависимости в файле composer.json вашего приложения:

• nunomaduro/collision to ^7.0
• phpunit/phpunit to ^10.0

И, наконец, рассмотрите другие сторонние пакеты, используемые вашим приложением, и убедитесь, что вы используете подходящую для Laravel 10 версию.

Минимальная стабильность

Вам следует обновить параметр minimum-stability в файле composer.json вашего приложения на значение stable. Или, поскольку значение minimum-stability по умолчанию равно stable, вы можете удалить этот параметр из файла composer.json:

"minimum-stability": "stable",

Приложение

Привязка публичного пути

Вероятность воздействия: Низкая

Если ваше приложение настраивает свой «публичный путь», привязывая path.public к контейнеру, вместо этого вам следует обновить ваш код и использовать метод usePublicPath, предлагаемый объектом Illuminate\Foundation\Application:

app()->usePublicPath(__DIR__.'/public');

Авторизация

Метод registerPolicies

Вероятность воздействия: Низкая

Метод registerPolicies в AuthServiceProvider теперь вызывается фреймворком автоматически. Следовательно, вы можете удалить его вызов из метода boot в AuthServiceProvider вашего приложения.

Кеш

Теги кэша Redis

Вероятность воздействия: Средняя

Использование Cache::tags() рекомендуется только для приложений, использующих Memcached. Если вы используете Redis в качестве драйвера кэша вашего приложения, рассмотрите возможность перехода на Memcached или использование альтернативного решения.

База данных

Вероятность воздействия: Средняя

Выражения базы данных

В Laravel 10.x выражения базы данных (обычно генерируемые через DB::raw) были переписаны для предоставления дополнительной функциональности в будущем. Важно отметить, что сырое строковое значение грамматики теперь должно быть получено через метод getValue(Grammar $grammar) выражения. Приведение выражения к строке с использованием (string) больше не поддерживается.

Обычно это не влияет на конечных пользователей приложения; однако, если ваше приложение вручную приводит выражения базы данных к строкам, используя (string) или вызывает метод __toString напрямую у выражения, вам следует обновить ваш код и вместо этого использовать метод getValue:

use Illuminate\Support\Facades\DB;

$expression = DB::raw('select 1');

$string = $expression->getValue(DB::connection()->getQueryGrammar());

Конструктор исключения запроса

Вероятность воздействия: Очень низкая

Конструктор Illuminate\Database\QueryException теперь принимает строку с именем подключения в качестве своего первого аргумента. Если ваше приложение вручную вызывает это исключение, вам следует соответственно изменить свой код.

ULID столбцы

Вероятность воздействия: Низкая

При использовании в миграциях метода ulid без аргументов, столбец теперь будет назван ulid. В предыдущих версиях Laravel, вызов этого метода без аргументов ошибочно создавал столбец с именем uuid:

$table->ulid();

Вы можете явно указать имя столбца при вызове метода ulid, передав имя столбца:

$table->ulid('ulid');

Eloquent

Свойство "Dates" модели

Вероятность воздействия: Средняя

Устаревшее свойство $dates в Eloquent-модели было удалено. Теперь ваше приложение должно использовать свойство $casts:

protected $casts = [
    'deployed_at' => 'datetime',
];

Локализация

Каталог языка

Вероятность воздействия: Нет

Хотя это не имеет отношения к существующим приложениям, стандартная структура приложения Laravel теперь по умолчанию не включает директорию lang. Вместо этого, при написании новых приложений Laravel ее можно опубликовать с использованием команды Artisan lang:publish:

php artisan lang:publish

Логирование

Monolog 3

Вероятность воздействия: Средняя

Зависимость Laravel от Monolog была обновлена до версии Monolog 3.x. Если вы напрямую взаимодействуете с Monolog в вашем приложении, вам следует ознакомиться с руководством по обновлению Monolog.

Если вы используете сторонние службы ведения журнала, такие как BugSnag или Rollbar, вам может потребоваться обновить эти сторонние пакеты до версии, поддерживающей Monolog 3.x и Laravel 10.x.

Очереди

Метод Bus::dispatchNow

Вероятность воздействия: Низкая

Устаревшие методы Bus::dispatchNow и dispatch_now были удалены. Вместо них ваше приложение должно использовать методы Bus::dispatchSync и dispatch_sync соответственно.

Возвращаемое значение помощника dispatch()

Вероятность воздействия: Низкая

Вызов dispatch с классом, который не реализует Illuminate\Contracts\Queue, ранее возвращал результат метода handle этого класса. Однако теперь это будет возвращён экземпляр Illuminate\Foundation\Bus\PendingBatch. Вы можете использовать dispatch_sync() чтобы вернуться к предыдущему поведению.

Маршрутизация

Псевдонимы Middleware

Вероятность воздействия: Опционально

В новых приложениях Laravel свойство $routeMiddleware класса App\Http\Kernel было переименовано в $middlewareAliases для более точного отражения его назначения. Вы можете переименовать это свойство в ваших существующих приложениях; однако это не обязательно.

Возвращаемое значение Rate Limiter

Вероятность воздействия: Низкая

При вызове метода RateLimiter::attempt значение, возвращаемое предоставленным замыканием, будет также возвращено самим методом. Если возвращаемое значение – null или отсутствует, метод attempt вернет true:

$value = RateLimiter::attempt('key', 10, fn () => ['example'], 1);

$value; // ['example']

Метод Redirect::home

Вероятность воздействия: Очень низкая

Устаревший метод Redirect::home был удален. Вместо этого ваше приложение должно выполнять перенаправление на явно указанный маршрут:

return Redirect::route('home');

Тестирование

Сервис Mocking

Вероятность воздействия: Средняя

Устаревший трейт MocksApplicationServices был удален из фреймворка. Этот трейт предоставлял методы тестирования, такие как expectsEvents, expectsJobs и expectsNotifications.

Если ваше приложение использует эти методы, мы рекомендуем переходить к использованию методов Event::fake, Bus::fake и Notification::fake соответственно. Вы можете узнать больше о подражании с помощью подделок в соответствующей документации для компонента, который вы пытаетесь фальсифицировать.

Валидация

Сообщения правила валидации на основе замыкания

Вероятность воздействия: Очень низкая

При написании пользовательских правил валидации на основе замыканий, вызов $fail более одного раза теперь добавит сообщения в массив, а не перезапишет предыдущее сообщение. Скорее всего это не повлияет на ваше приложение.

Кроме того, коллбэк $fail теперь возвращает объект. Если вы ранее указывали тип возвращаемого значения в замыкании валидации, это может потребовать обновления вашего типа:

public function rules()
{
    'name' => [
        function ($attribute, $value, $fail) {
            $fail('validation.translation.key')->translate();
        },
    ],
}

Сообщения о валидации и правила на основе замыканий

Вероятность воздействия: Очень низкая

Ранее вы могли назначить сообщение об ошибке другому ключу, предоставив массив в $fail в правилах валидации на основе замыканий. Однако теперь вы должны предоставить ключ в качестве первого аргумента, а сообщение об ошибке – в качестве второго аргумента:

Validator::make([
    'foo' => 'string',
    'bar' => [function ($attribute, $value, $fail) {
        $fail('foo', 'Something went wrong!');
    }],
]);

Метод after запроса формы

Вероятность воздействия: Очень низкая

Метод after внутри запросов формы теперь зарезервирован Laravel.

Если в ваших запросах формы определён метод after, этот метод следует переименовать или изменить, чтобы использовать новую функциональность “после валидации” в запросах формы Laravel.

Разное

Мы также рекомендуем вам просматривать изменения в GitHub-репозитории laravel/laravel. Хотя многие из этих изменений могут быть неважны, но вы можете синхронизировать эти файлы с вашим приложением. Некоторые из этих изменений будут рассмотрены в данном руководстве по обновлению, но другие, такие как изменения файлов конфигурации или комментарии, не будут.

Вы можете легко просмотреть изменения с помощью инструмента сравнения GitHub и выбрать, какие обновления важны для вас. Тем не менее, многие изменения, показанные инструментом сравнения GitHub, связаны с принятием нативных типов PHP в нашей организации. Эти изменения обратно совместимы, и их принятие во время миграции на Laravel 10 является необязательным.