Skip to content

Hướng dẫn nâng cấp (Upgrade Guide) ​

Thay đổi ảnh hưởng cao (High Impact Changes) ​

Thay đổi ảnh hưởng trung bình (Medium Impact Changes) ​

Thay đổi ảnh hưởng thấp (Low Impact Changes) ​

Nâng cấp lên 13.0 từ 12.x ​

Thời gian nâng cấp ước tính: 10 phút ​

GỢI Ý

Chúng tôi cố gắng ghi lại mọi breaking change có thể. Vì một số thay đổi nằm ở các phần ít dùng của framework, chỉ một phần nhỏ thực sự ảnh hưởng đến ứng dụng của bạn. Để tiết kiệm thời gian, hãy cân nhắc sử dụng Shift — dịch vụ tự động hóa nâng cấp Laravel do cộng đồng duy trì.

Cập nhật Dependencies ​

Mức ảnh hưởng: Cao

Cập nhật các dependency sau trong file composer.json:

  • laravel/framework → ^13.0
  • phpunit/phpunit → ^12.0
  • pestphp/pest → ^4.0

Cập nhật Laravel Installer ​

Nếu sử dụng Laravel installer CLI, cập nhật cho tương thích Laravel 13.x:

bash
composer global update laravel/installer

Nếu dùng Laravel Herd, cập nhật Herd lên bản mới nhất.

Security ​

Request Forgery Protection ​

Mức ảnh hưởng: Cao

Middleware CSRF đã đổi tên từ VerifyCsrfToken thành PreventRequestForgery, và bổ sung kiểm tra origin request qua header Sec-Fetch-Site:

php
use Illuminate\Foundation\Http\Middleware\PreventRequestForgery;
use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken;

// Laravel <= 12.x
->withoutMiddleware([VerifyCsrfToken::class]);

// Laravel >= 13.x
->withoutMiddleware([PreventRequestForgery::class]);

VerifyCsrfToken và ValidateCsrfToken vẫn hoạt động như deprecated alias, nhưng nên cập nhật sang PreventRequestForgery.

Cache ​

Cache serializable_classes Configuration ​

Mức ảnh hưởng: Trung bình

Cấu hình serializable_classes trong cache cho phép hạn chế các class được phép deserialize.

Mức ảnh hưởng: Thấp

Container ​

Container::call và Nullable Class Defaults ​

Mức ảnh hưởng: Thấp

Database ​

MySQL DELETE Queries với JOIN, ORDER BY và LIMIT ​

Mức ảnh hưởng: Thấp

Laravel giờ biên dịch đầy đủ query DELETE ... JOIN bao gồm ORDER BY và LIMIT cho MySQL grammar. Ở phiên bản trước, các clause này có thể bị bỏ qua trên joined deletes. Trong Laravel 13, chúng được bao gồm trong SQL sinh ra — database engine không hỗ trợ cú pháp này có thể throw QueryException.

Eloquent ​

Model Booting và Nested Instantiation ​

Mức ảnh hưởng: Rất thấp

Tạo model instance mới khi model đang boot giờ bị cấm và throw LogicException:

php
protected static function boot()
{
    parent::boot();

    // Không còn được phép khi đang boot...
    (new static())->getTable();
}

Di chuyển logic này ra ngoài boot cycle.

Polymorphic Pivot Table Name Generation ​

Mức ảnh hưởng: Thấp

Khi tên bảng được suy ra cho polymorphic pivot model dùng custom pivot class, Laravel giờ tạo tên ở dạng số nhiều (pluralized).

Collection Model Serialization khôi phục Eager-Loaded Relations ​

Mức ảnh hưởng: Thấp

Khi Eloquent model collection được serialize và khôi phục (ví dụ trong queued jobs), eager-loaded relations giờ được khôi phục.

Queue ​

JobAttempted Event Exception Payload ​

Mức ảnh hưởng: Thấp

Event Illuminate\Queue\Events\JobAttempted giờ expose object exception (hoặc null) qua $exception, thay thế property boolean $exceptionOccurred:

php
// Laravel <= 12.x
$event->exceptionOccurred;

// Laravel >= 13.x
$event->exception;

QueueBusy Event Property Rename ​

Mức ảnh hưởng: Thấp

Property $connection trên event QueueBusy đã đổi tên thành $connectionName.

Routing ​

Domain Route Registration Precedence ​

Mức ảnh hưởng: Thấp

Route có domain cụ thể (explicit) giờ được ưu tiên trước route không có domain trong route matching.

Scheduling ​

withScheduling Registration Timing ​

Mức ảnh hưởng: Rất thấp

Schedule đăng ký qua ApplicationBuilder::withScheduling() giờ được defer cho đến khi Schedule được resolve.

Support ​

Manager extend Callback Binding ​

Mức ảnh hưởng: Thấp

Custom driver closure đăng ký qua method extend giờ được bind vào manager instance. Nếu trước đó dùng object khác làm $this trong callback, sử dụng use (...) để capture.

Str Factories Reset Between Tests ​

Mức ảnh hưởng: Thấp

Laravel giờ reset custom Str factories trong test teardown. Thiết lập lại trong mỗi test hoặc setup hook nếu cần.

Js::from sử dụng Unescaped Unicode mặc định ​

Mức ảnh hưởng: Rất thấp

Illuminate\Support\Js::from giờ dùng JSON_UNESCAPED_UNICODE mặc định.