Опубликовано:

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

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

Изменения с высоким уровнем влияния

Изменения со средним уровнем влияния

Изменения с низким уровнем влияния

Мы стараемся документировать все изменения. Некоторые изменения находятся в малоизвестных частях фреймворка, лишь часть из них может повлиять на ваше приложение

Обновление до версии 11.0 с версии 10.x

Примерное время обновления: 15 минут

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

Вероятность влияния: Высокая

Требуется PHP 8.2.0

Laravel 11 требует PHP 8.2.0 или более поздней версии.

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

Необходимо обновить следующие зависимости в файле composer.json вашего приложения:

Если приложение использует Laravel Cashier Stripe, Passport, Sanctum, Spark Stripe или Telescope, вам нужно опубликовать их миграции в своём приложении. Cashier Stripe, Passport, Sanctum, Spark Stripe и Telescope больше не загружают миграции автоматически из собственного каталога migrations. Поэтому для публикации их миграций в приложении необходимо выполнить следующую команду:

php artisan vendor:publish --tag=cashier-migrations
php artisan vendor:publish --tag=passport-migrations
php artisan vendor:publish --tag=sanctum-migrations
php artisan vendor:publish --tag=spark-migrations
php artisan vendor:publish --tag=telescope-migrations

Кроме того, необходимо просмотреть руководства по обновлению для каждого из этих пакетов, чтобы убедиться, что вы знаете обо всех дополнительных изменениях:

Если вы установили инсталлятор Laravel вручную, необходимо обновить его через Composer:

composer global require laravel/installer:^5.6

Кроме того, можно удалить зависимость Composer doctrine/dbal, если ранее она была добавлена в приложение, поскольку Laravel больше не зависит от этого пакета.

Структура приложения

Вероятность влияния: Высокая

Laravel 11 представляет новую структуру приложения по умолчанию с меньшим количеством файлов. А именно, новые приложения Laravel содержат меньше сервис-провайдеров, middleware и конфигурационных файлов.

Однако мы не рекомендуем приложениям Laravel 10, обновляющимся до Laravel 11, пытаться изменить структуру приложения, поскольку Laravel 11 был тщательно настроен для поддержки структуры приложений Laravel 10.

Аутентификация

Перехеширование паролей

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

Laravel 11 автоматически перехеширует пароли пользователей при аутентификации, если "коэффициента работы" алгоритма хеширования был обновлён с момента последнего хеширования пароля.

Обычно это не мешает работе приложения; однако можно отключить это поведение, добавив опцию rehash_on_login в конфигурационный файл config/hashing.php приложения:

'rehash_on_login' => false,

Контракт UserProvider

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

Контракт Illuminate\Contracts\Auth\UserProvider получил новый метод rehashPasswordIfRequired. Этот метод отвечает за повторное хэширование и сохранение пароля пользователя в хранилище при изменении коэффициента работы алгоритма хэширования.

Если приложение или пакет определяют класс, реализующий этот интерфейс, необходимо добавить новый метод rehashPasswordIfRequired в его реализацию. Эталонную реализацию можно найти в классе Illuminate\Auth\EloquentUserProvider:

public function rehashPasswordIfRequired(Authenticatable $user, array $credentials, bool $force = false);

Контракт Authenticatable

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

Контракт Illuminate\Contracts\Auth\Authenticatable получил новый метод getAuthPasswordName. Этот метод отвечает за возврат имени колонки паролей вашей аутентифицируемой сущности.

Если в приложении или пакете определён класс, реализующий этот интерфейс, необходимо добавить новый метод getAuthPasswordName в его реализацию:

public function getAuthPasswordName()
{
    return 'password';
}

Модель User по умолчанию, входящая в состав Laravel, получает этот метод автоматически, поскольку он включён в трейт Illuminate\Auth\Authenticatable.

Кэш

Префиксы ключей кэша

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

Ранее, если префикс ключа кэша был определён для кэш-хранилищ DynamoDB, Memcached или Redis, Laravel добавлял к префиксу :. В Laravel 11 префикс ключа кэша не получает суффикс :. Если вы хотите сохранить прежнее поведение префикса, вы можете вручную добавить суффикс : к префиксу ключа кэша.

Коллекции

Контракт Enumerable

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

Обновлён метод dump контракта Illuminate\Support\Enumerable, теперь он принимает переменный аргумент ...$args. Если вы реализуете этот интерфейс, необходимо соответствующим образом обновить свою реализацию:

public function dump(...$args);

База данных

SQLite 3.35.0+

Вероятность влияния: Высокая

Если приложение использует базу данных SQLite, требуется версия SQLite 3.35.0 или выше.

Модель Eloquent метод casts

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

Базовый класс модели Eloquent теперь определяет метод casts для поддержки определения каста атрибутов. Если одна из моделей приложения определяет отношение casts, оно может конфликтовать с методом casts, присутствующим в базовом классе модели Eloquent.

Модификация столбцов

Вероятность влияния: Высокая

При изменении столбца теперь необходимо явно указать все модификаторы, которые необходимо сохранить в определении столбца после его изменения. Все отсутствующие атрибуты будут удалены. Например, чтобы сохранить атрибуты unsigned, default и comment, необходимо явно вызвать каждый модификатор при изменении столбца, даже если эти атрибуты были назначены столбцу при предыдущей миграции.

Например, представьте, что у вас есть миграция, создающая столбец votes с атрибутами unsigned, default и comment:

Schema::create('users', function (Blueprint $table) {
    $table->integer('votes')->unsigned()->default(1)->comment('The vote count');
});

Позже вы написали миграцию, изменяющую столбец на nullable:

Schema::table('users', function (Blueprint $table) {
    $table->integer('votes')->nullable()->change();
});

В Laravel 10 при миграции сохранялись атрибуты unsigned, default и comment для столбца. Однако в Laravel 11 миграция должна также включать все атрибуты, определённые ранее для столбца. В противном случае они будут удалены:

Schema::table('users', function (Blueprint $table) {
    $table->integer('votes')
        ->unsigned()
        ->default(1)
        ->comment('The vote count')
        ->nullable()
        ->change();
});

Метод change не изменяет индексы столбца. Поэтому для явного добавления или удаления индекса при изменении столбца можно использовать модификаторы индекса:

// Добавляем индекс...
$table->bigIncrements('id')->primary()->change();

// Удаляем индекс...
$table->char('postal_code', 10)->unique(false)->change();

Если вы не хотите обновлять все существующие миграции "change" в приложении, для сохранения существующих атрибутов столбца, можно просто "сжать" миграции:

php artisan schema:dump

После того как миграции будут "сжаты", Laravel "перенесёт" базу данных, используя файл схемы приложения, прежде чем запустить оставшиеся миграции.

Типы с плавающей точкой

Вероятность влияния: Высокая

Типы столбцов миграции double и float были переписаны, для согласованности во всех базах данных.

Тип столбца double теперь создаёт эквивалентный столбец DOUBLE без общего количества цифр и мест (цифр после десятичной точки), что является стандартным синтаксисом SQL. Поэтому вы можете удалить аргументы $total и $places:

$table->double('amount');

Тип столбца float создаёт столбец, эквивалентный FLOAT, без общего количества цифр и мест (цифр после запятой), но с необязательной спецификацией $precision для определения размера хранения в виде 4-байтного столбца с одинарной точностью или 8-байтного столбца с двойной точностью. Поэтому вы можете удалить аргументы $total и $places и указать необязательное значение $precision в соответствии с документацией вашей базы данных:

$table->float('amount', precision: 53);

Методы unsignedDecimal, unsignedDouble и unsignedFloat были удалены, поскольку модификатор unsigned для этих типов столбцов устарел в MySQL и никогда не был стандартизирован в других системах баз данных. Однако, если вы хотите продолжать использовать устаревший атрибут unsigned, вы можете добавить метод unsigned в определение столбца:

$table->decimal('amount', total: 8, places: 2)->unsigned();
$table->double('amount')->unsigned();
$table->float('amount', precision: 53)->unsigned();

Отдельный драйвер MariaDB

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

Вместо использования драйвера MySQL при подключении к базам данных MariaDB, Laravel 11 добавляет отдельный драйвер базы данных для MariaDB.

Если ваше приложение подключается к базе данных MariaDB, можно обновить конфигурацию подключения на новый драйвер mariadb, чтобы в будущем воспользоваться возможностями, специфичными для MariaDB:

'driver' => 'mariadb',
'url' => env('DB_URL'),
'host' => env('DB_HOST', '127.0.0.1'),
'port' => env('DB_PORT', '3306'),
// ...

В настоящее время новый драйвер MariaDB ведёт себя так же, как и текущий драйвер MySQL, за одним исключением: метод построения схемы uuid создаёт собственные столбцы UUID вместо столбцов char(36).

Если ваши существующие миграции используют метод uuid для построения схемы, а вы решили использовать новый драйвер базы данных mariadb, необходимо обновить вызовы метода uuid в миграции до char, чтобы избежать изменений или неожиданного поведения:

Schema::table('users', function (Blueprint $table) {
    $table->char('uuid', 36);

    // ...
});

Пространственные типы

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

Типы пространственных столбцов в миграциях баз данных были переписаны таким образом, чтобы быть согласованными во всех базах данных. Поэтому можно удалить из миграций методы point, lineString, polygon, geometryCollection, multiPoint, multiLineString, multiPolygon и multiPolygonZ и использовать вместо них методы geometry или geography:

$table->geometry('shapes');
$table->geography('coordinates');

Для явного ограничения типа или идентификатора пространственной системы ссылок для значений, хранящихся в столбце на MySQL, MariaDB и PostgreSQL, вы можете передать методу subtype и srid:

$table->geometry('dimension', subtype: 'polygon', srid: 0);
$table->geography('latitude', subtype: 'point', srid: 4326);

Соответственно, модификаторы столбца isGeometry и projection в грамматике PostgreSQL были удалены.

Удаление DBAL доктрины

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

Следующий список классов и методов, связанных с Doctrine DBAL, был удалён. Laravel больше не зависит от этого пакета, и регистрация пользовательских типов Doctrines больше не требуется для правильного создания и изменения различных типов колонок, которые ранее требовали:

Кроме того, больше не требуется регистрировать пользовательские типы Doctrine через dbal.types в файле конфигурации database приложения.

Если вы ранее использовали Doctrine DBAL для проверки базы данных и связанных с ней таблиц, то вместо этого можно использовать новые методы нативной схемы Laravel (Schema::getTables(), Schema::getColumns(), Schema::getIndexes(), Schema::getForeignKeys() и т. д.).

Устаревшие методы схемы

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

Устаревшие методы Schema::getAllTables(), Schema::getAllViews() и Schema::getAllTypes(), основанные на Doctrine, были удалены в пользу новых нативных методов Laravel — Schema::getTables(), Schema::getViews() и Schema::getTypes().

При использовании PostgreSQL и SQL Server ни один из новых методов схемы не примет трёхкомпонентную ссылку (например, database.schema.table). Поэтому для объявления базы данных следует использовать connection():

Schema::connection('database')->hasTable('schema.table');

Метод getColumnType() построителя схемы

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

Метод Schema::getColumnType() теперь всегда возвращает фактический тип заданного столбца, а не тип, эквивалентный типу Doctrine DBAL.

Интерфейс подключения к базе данных

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

Интерфейс Illuminate\Database\ConnectionInterface получил новый метод scalar. Если вы определяете собственную реализацию этого интерфейса, необходимо добавить метод scalar в реализацию:

public function scalar($query, $bindings = [], $useReadPdo = true);

Даты

Carbon 3

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

Laravel 11 поддерживает Carbon 2 и Carbon 3. Carbon — это библиотека для работы с датами, широко используемая в Laravel и пакетах по всей экосистеме. Если устанавливаете Carbon 3, вам следует просмотреть change log Carbon.

Почта

Контракт Mailer

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

Контракт Illuminate\Contracts\Mail\Mailer получил новый метод sendNow. Если приложение или пакет реализует этот контракт вручную, необходимо добавить новый метод sendNow в реализацию:

public function sendNow($mailable, array $data = [], $callback = null);

Пакеты

Публикация сервис-провайдеров в приложении

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

Если вы создали пакет Laravel, вручную публикующий сервис-провайдера в каталоге приложения app/Providers и вручную изменяющий конфигурационный файл config/app.php для регистрации сервис-провайдера, необходимо обновить пакет, чтобы он использовал новый метод ServiceProvider::addProviderToBootstrapFile.

Метод addProviderToBootstrapFile автоматически добавит опубликованного провайдера в файл приложения bootstrap/providers.php, поскольку массив providers не существует в файле конфигурации config/app.php в новых приложениях Laravel 11.

use Illuminate\Support\ServiceProvider;

ServiceProvider::addProviderToBootstrapFile(Provider::class);

Очереди

Интерфейс BatchRepository

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

Интерфейс Illuminate\Bus\BatchRepository получил новый метод rollBack. Если вы реализуете этот интерфейс в своём пакете или приложении, необходимо добавить этот метод в вашу реализацию:

public function rollBack();

Синхронные задания в транзакциях базы данных

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

Ранее синхронные задания (задания, использующие драйвер очереди sync) выполнялись немедленно, независимо от того, был ли параметр конфигурации after_commit соединения очереди установлен в true или для задания был вызван метод afterCommit.

В Laravel 11 синхронные задания очереди теперь будут учитывать конфигурацию "после коммита" соединения очереди или задания.

Ограничение соединений

Посекундное ограничение соединений

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

Laravel 11 поддерживает посекундное ограничение соединений вместо поминутного. С этим изменением связан целый ряд потенциальных сбоев, о которых следует знать.

Конструктор класса GlobalLimit теперь принимает секунды вместо минут. Этот класс не документирован и обычно не используется в приложениях:

new GlobalLimit($attempts, 2 * 60);

Конструктор класса Limit теперь принимает секунды вместо минут. Все документированные случаи использования этого класса ограничиваются статическими конструкторами, такими как Limit::perMinute и Limit::perSecond. Однако, если вы создаёте экземпляр класса вручную, необходимо обновить приложение, чтобы в конструктор класса передавались секунды:

new Limit($key, $attempts, 2 * 60);

Свойство decayMinutes класса Limit было переименовано в decaySeconds и теперь содержит секунды вместо минут.

Конструкторы классов Illuminate\Queue\Middleware\ThrottlesExceptions и Illuminate\Queue\Middleware\ThrottlesExceptionsWithRedis теперь принимают секунды вместо минут:

new ThrottlesExceptions($attempts, 2 * 60);
new ThrottlesExceptionsWithRedis($attempts, 2 * 60);

Cashier Stripe

Обновление Cashier Stripe

Вероятность влияния: Высокая

Laravel 11 больше не поддерживает Cashier Stripe 14.x. Поэтому следует обновить зависимость Laravel Cashier Stripe для приложения до ^15.0 в файле composer.json.

Cashier Stripe 15.0 больше не загружает миграции автоматически из собственной директории migrations. Вместо этого необходимо выполнить следующую команду, чтобы опубликовать миграции Cashier Stripe в приложении:

php artisan vendor:publish --tag=cashier-migrations

Пожалуйста, ознакомьтесь с полным руководством по обновлению Cashier Stripe, чтобы узнать о дополнительных изменениях влияющих на совместимость.

Spark (Stripe)

Обновление Spark Stripe

Вероятность влияния: Высокая

Laravel 11 больше не поддерживает Laravel Spark Stripe 4.x. Поэтому необходимо обновить зависимость Laravel Spark Stripe для приложения до ^5.0 в файле composer.json.

Spark Stripe 5.0 больше не загружает миграции автоматически из собственного каталога migrations. Вместо этого необходимо выполнить следующую команду, чтобы опубликовать миграции Spark Stripe в приложении:

php artisan vendor:publish --tag=spark-migrations

Пожалуйста, ознакомьтесь с полным руководством по обновлению Spark Stripe, чтобы узнать о дополнительных изменениях влияющих на совместимость.

Passport

Обновление Passport

Вероятность влияния: Высокая

Laravel 11 больше не поддерживает Laravel Passport 11.x. Поэтому необходимо обновить зависимость Laravel Passport для приложения до ^12.0 в файле composer.json.

Passport 12.0 больше не загружает миграции автоматически из собственного каталога migrations. Вместо этого необходимо выполнить следующую команду, чтобы опубликовать миграции Passport в приложении:

php artisan vendor:publish --tag=passport-migrations

Кроме того, по умолчанию тип предоставления пароля отключён. Вы можете включить его, вызвав метод enablePasswordGrant в методе boot AppServiceProvider приложения:

public function boot(): void
{
    Passport::enablePasswordGrant();
}

Sanctum

Обновление Sanctum

Вероятность влияния: Высокая

Laravel 11 больше не поддерживает Laravel Sanctum 3.x. Поэтому необходимо обновить зависимость Laravel Sanctum для приложения до ^4.0 в файле composer.json.

Sanctum 4.0 больше не загружает миграции автоматически из собственного каталога миграций. Вместо этого следует выполнять следующую команду для публикации миграций Sanctum в приложении:

php artisan vendor:publish --tag=sanctum-migrations

Затем в конфигурационном файле config/sanctum.php приложения следует обновить ссылки на middleware authenticate_session, encrypt_cookies и validate_csrf_token следующим образом:

'middleware' => [
    'authenticate_session' => Laravel\Sanctum\Http\Middleware\AuthenticateSession::class,
    'encrypt_cookies' => Illuminate\Cookie\Middleware\EncryptCookies::class,
    'validate_csrf_token' => Illuminate\Foundation\Http\Middleware\ValidateCsrfToken::class,
],

Telescope

Обновление Telescope

Вероятность влияния: Высокая

Laravel 11 больше не поддерживает Laravel Telescope 4.x. Поэтому необходимо обновить зависимость Laravel Telescope для приложения до ^5.0 в файле composer.json.

Telescope 5.0 больше не загружает миграции автоматически из собственного каталога migrations. Вместо этого необходимо выполнить следующую команду, чтобы опубликовать миграции Telescope в приложении:

php artisan vendor:publish --tag=telescope-migrations

Пакет Spatie Once

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

Laravel 11 теперь предоставляет собственную функцию once, чтобы гарантировать, что данное замыкание будет выполнено только один раз. Поэтому, если ваше приложение содержит зависимость от пакета spatie/once, необходимо удалить его из файла composer.json приложения, чтобы избежать возникновения конфликтов.

Разное

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

Предыдущая Статья

Стратегии оптимизации производительности Laravel

Следующая Статья

Декодирование специфичности CSS