Nâng cấp Laravel 13: Checklist 10 bước cần kiểm tra

PHP 8.3 là điều kiện bắt buộc?

Laravel 13 chính thức yêu cầu PHP 8.3 trở lên — đây là thay đổi quan trọng nhất mà bạn cần kiểm tra trước khi nâng cấp. Phiên bản PHP 8.1 đã chính thức end-of-life vào tháng 12/2025, và Laravel 13 không còn hỗ trợ PHP 8.2 [1]. Nếu bạn chưa biết Laravel 13 có gì mới, hãy đọc bài Laravel 13 Có Gì Mới? trước nhé!

Bạn có đang chạy PHP 8.3 chưa? Hãy kiểm tra ngay:

php -v

Nếu output hiển thị PHP 8.3.x → bạn đã sẵn sàng. Nếu là PHP 8.2 hoặc thấp hơn → cần nâng cấp PHP runtime trước khi chạy upgrade Laravel. Đây là “show stopper” của Laravel 13 — không thể bỏ qua bước này [2].

Lời khuyên của mình: Nâng cấp PHP lên 8.3 trước, sau đó mới chạy upgrade Laravel. Đừng làm ngược lại!

Kiểm tra staging environment

Staging environment là nơi bạn cần test đầu tiên trước khi đụng đến production. Mọi ứng dụng Laravel đều nên có staging để verify các thay đổi trước khi deploy thật.

Đảm bảo staging environment của bạn:

• Đồng bộ hoàn toàn với production (cùng PHP version, cùng dependencies)
• Có dữ liệu mẫu đủ để test các flows chính
• Có quyền debug để xem lỗi chi tiết

Staging giúp bạn phát hiện vấn đề trước khi ảnh hưởng đến người dùng thật. Đừng bao giờ upgrade trực tiếp trên production!

Backup database

Backup database là bước không thể bỏ qua dù Laravel 13 có zero breaking changes. Trước khi chạy bất kỳ migration nào, hãy đảm bảo bạn có bản backup mới nhất.

Các loại backup cần thực hiện:

• Full database backup — dùng mysqldump hoặc tool của hosting
• Verify backup thành công — restore thử trên local để chắc chắn
• Backup config files — đặc biệt .env và các file cấu hình custom

Thú vị nhỉ! Nhiều dev skip bước này vì nghĩ “upgrade nhẹ không sao” — nhưng mất data mới là thứ không bao giờ muốn xảy ra.

Kiểm tra test suite

Chạy full test suite và đảm bảo 100% pass trước khi upgrade. Đây là cách tốt nhất để verify ứng dụng hoạt động đúng sau khi nâng cấp.

php artisan test

Hoặc nếu dùng PHPUnit trực tiếp:

./vendor/bin/phpunit

Nếu test fail → sửa các lỗi test trước. Test suite pass là điều kiện tiên quyết để tiếp tục. Mình khuyên bạn nên commit code hiện tại vào git branch riêng trước khi upgrade — dễ rollback nếu cần.

Một số thay đổi trong PHPUnit 12 (đi kèm Laravel 13) có thể ảnh hưởng đến test của bạn [3]. Và nếu bạn muốn adopt PHP Attributes — feature mới trong Laravel 13 — hãy đọc hướng dẫn Migration PHP Attributes Laravel 13 nhé!

Cập nhật composer.json

Đây là bước core của upgrade process. Bạn cần cập nhật các dependencies chính trong composer.json.

Mở file composer.json và cập nhật:

"require": {
    "php": "^8.3",
    "laravel/framework": "^13.0",
    "laravel/boost": "^2.0",
    "laravel/tinker": "^3.0"
}

Kiểm tra xem các package third-party có bản compatible với Laravel 13 chưa. Đặc biệt:

• Các package liên quan đến AI (nếu đang dùng) — so sánh với Laravel AI SDK mới
• Custom middleware CSRF — đổi tên từ VerifyCsrfToken thành PreventRequestForgery [4]
• Package liên quan đến cache và session

Đừng quên kiểm tra Packagist để xem các package của bạn có bản Laravel 13 compatible không nhé!

Chạy composer update

Sau khi cập nhật composer.json, chạy composer update để tải Laravel 13 về.

composer update laravel/framework laravel/boost laravel/tinker --with-all-dependencies

Flag --with-all-dependencies đảm bảo tất cả related packages cũng được update theo. Quá trình này có thể mất vài phút tùy vào số lượng dependencies.

Nếu gặp conflict → kiểm tra lại các package third-party. Có thể cần update chúng lên bản mới hơn hoặc tìm alternative.

Tip nhỏ: Chạy composer update trên local trước để debug dễ hơn, sau đó mới apply lên staging/production.

Clear cache và optimize

Sau khi composer update hoàn tất, clear tất cả cache để đảm bảo Laravel dùng config mới.

php artisan config:clear
php artisan cache:clear
php artisan view:clear
php artisan route:clear
php artisan optimize

Các lệnh này xóa cache cũ và regenerate files với Laravel 13. Đây là bước quan trọng — nhiều lỗi sau upgrade là do cache không được clear đúng cách.

Kiểm tra các thay đổi quan trọng

Dù Laravel 13 có zero breaking changes ở framework level, có một số thay đổi bạn cần lưu ý.

1. Cache Prefixes

Laravel 13 thay đổi default cache prefix. Nếu bạn dùng shared Redis hoặc cache driver chung → cần cập nhật config [5]:

// Laravel >= 13.x
Str::slug((string) env('APP_NAME', 'laravel')).'-cache-';

2. CSRF Middleware Rename

Middleware chống CSRF đổi tên từ VerifyCsrfToken thành PreventRequestForgery. Nếu bạn có custom CSRF middleware → cần update references [4].

3. Pagination View Names

View names cho Bootstrap 3 pagination thay đổi:

// Laravel <= 12.x
pagination::default

// Laravel >= 13.x
pagination::bootstrap-3

4. Queue Configuration

Nếu dùng queue với failover driver → cần test lại vì behavior có thay đổi nhỏ.

5. Collection Model Serialization

Eager-loaded relations trong collections được preserve tốt hơn. Đây là improvement, không phải breaking change.

Mình khuyên bạn nên dùng Laravel Shift hoặc Rector để scan các deprecated methods tự động [6].

Test trên staging

Đây là bước quan trọng nhất trước khi deploy production. staging phải pass toàn bộ test cases trước khi tiếp tục.

Test các scenarios chính:

• Đăng nhập/đăng ký user
• CRUD operations trên data
• API endpoints
• File upload/download
• Queue jobs processing
• Email sending
• Payment flows (nếu có)

Đừng quên test các edge cases và error handling. Production-like testing trên staging giúp bạn tự tin hơn khi deploy.

Nhiều team skip staging testing vì “nhanh” — nhưng thường mất nhiều thời gian fix bug production hơn!

Deploy production

Sau khi staging pass toàn bộ tests → deploy lên production. Quy trình deploy nên:

1. Deploy vào maintenance mode — ngăn user truy cập trong lúc upgrade
2. Chạy migrations (nếu có)
3. Clear cache lần cuối
4. Exit maintenance mode
5. Monitor logs — theo dõi error logs trong 24h đầu

php artisan down
git pull
composer install --optimize-autoloader
php artisan migrate
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan up

Đặc biệt chú ý --optimize-autoloader thay vì composer update trên production — nhanh hơn và an toàn hơn.

Xử lý lỗi thường gặp

Dù upgrade “mượt” nhưng biết trước các lỗi thường gặp giúp bạn xử lý nhanh hơn.

Lỗi 1: “Class not found” sau khi upgrade

Nguyên nhân: Package chưa được autoload đúng cách.

Cách fix:

composer dump-autoload
php artisan config:clear

Lỗi 2: PHP version mismatch

Nguyên nhân: Server vẫn chạy PHP 8.2.

Cách fix: Contact hosting/server admin để upgrade PHP lên 8.3.

Lỗi 3: Cache driver không hoạt động

Nguyên nhân: Cache prefix thay đổi, old cached data không tương thích.

Cách fix:

php artisan cache:clear

Lỗi 4: Queue job fail

Nguyên nhân: Job signature hoặc properties thay đổi.

Cách fix: Review queue config mới với Queue::route() method [7].

Lỗi 5: CSRF token mismatch

Nguyên nhân: CSRF middleware đổi tên.

Cách fix: Verify kernel.php hoặc bootstrap/app.php có dùng middleware mới.

Tổng kết

Nâng cấp Laravel 13 thực ra khá đơn giản nếu bạn làm đúng checklist. Với PHP 8.3, zero breaking changes, và khoảng 10 phút cho standard app — đây là một trong những upgrade dễ nhất của Laravel.

Tuy nhiên, đừng vì vậy mà chủ quan. Staging test, backup data, và clear cache là 3 bước không thể skip.

Nếu bạn gặp khó khăn trong quá trình upgrade hoặc có câu hỏi nào → để lại comment nhé, mình sẽ hỗ trợ!

Đừng quên share bài này nếu thấy hữu ích!

Nguồn tham khảo

1. Laravel News – Laravel 13 Released
2. Medium – Laravel 13 Features
3. Laravel Official – Upgrade Guide
4. Impact Tech Lab – Laravel 13 Release
5. Bacancy Technology – Laravel 13 Guide