Học Laravel 13 – Bài 36: Nâng cấp Laravel và quản lý dependency có kiểm soát

Bài 36 — Quản lý dependency và nâng cấp Laravel: Nâng cấp là thay đổi một tập hợp ràng buộc và hành vi, không chỉ sửa số phiên bản trong composer.json. Với TaskFlow, mục tiêu là giữ bản cài có thể tái tạo, biết package nào thay đổi và có bằng chứng regression trước khi phát hành.

1. Ghi baseline trước khi thay đổi

Checkpoint hiện tại dùng Laravel framework 13.32.0, PHP 8.4.25, Pest 4.7.8 và PHPUnit 12.5.33. Laravel có yêu cầu nền riêng nhưng lockfile cùng dev dependencies có thể yêu cầu runtime khác; kiểm tra chính tập package đã khóa. PHP CLI local, FPM production và runner CI không được mặc định là cùng phiên bản.

Làm trên nhánh hoặc release thử nghiệm, ghi lý do nâng cấp, runtime, hash lockfile và trạng thái worktree. Không xóa thay đổi chưa commit của người khác để tạo cảm giác repository sạch. Bộ lệnh kiểm tra dưới đây không yêu cầu sửa lockfile:

composer validate --strict
composer check-platform-reqs
composer show --locked laravel/framework
composer audit --locked
npm audit --audit-level=high
composer update laravel/framework --with-dependencies --dry-run

# Inspect a concrete dependency constraint:
composer why guzzlehttp/guzzle
composer why-not guzzlehttp/guzzle 8.2.0

2. Đọc kết quả thực tế

Composer audit --locked không báo advisory; npm audit báo 0 vulnerabilities. Dry-run riêng Laravel trả “Nothing to modify in lock file”, nên bài này không thực hiện nâng cấp package. Kết quả phụ thuộc thời điểm, repository package và các constraint đang dùng; không được suy ra mọi dependency đều là bản mới nhất hoặc không có lỗi chưa công bố.

why cho biết ai kéo một package vào dependency graph. why-not với target cụ thể chỉ ra constraint đang ngăn lựa chọn đó; output Guzzle 8.2.0 hiện nhắc promises/psr7 đang khóa ở nhánh khác. Không hiểu exit code khác 0 của chẩn đoán blocker thành lý do chạy force. Dùng dry-run để xem toàn bộ phương án giải trước khi quyết định.

3. Install, update và lockfile

Release cài từ lockfile đã review bằng composer install, không chạy update tùy ý trên server. Khi chủ động đổi dependency, update phạm vi hẹp và review diff manifest/lock. Với frontend, npm ci phục vụ bản cài theo package-lock. Giữ cả hai lockfile trong repository; không xóa chúng chỉ để che lỗi dependency.

-w/--with-dependencies và -W/--with-all-dependencies có phạm vi khác nhau; -W cho phép dịch chuyển thêm root requirements. Không dùng nó theo phản xạ mỗi khi resolver thất bại. Xem package mới, bị gỡ, downgrade, version transitive và plugin/script sẽ chạy. Không --ignore-platform-reqs để cài một bản runtime không đáp ứng.

4. Bài học từ TaskFlow

Khi bổ sung Reverb, graph đã phải điều chỉnh các package HTTP đang khóa. Khi thêm Pest 4, PHPUnit đổi patch từ 12.5.35 sang 12.5.33 theo constraint của Pest. Những thay đổi này đã được dry-run, cài có chủ đích và chạy lại suite; chúng cho thấy “thêm một package” không đồng nghĩa chỉ thêm một dòng.

Không nâng major Pest chỉ vì xuất hiện bản mới trong tài liệu mặc định. Chọn tài liệu đúng nhánh, kiểm tra PHP/PHPUnit/plugin Laravel cùng lúc. Với nâng Laravel major, đọc upgrade guide của phiên bản đích và rà middleware, authentication, serialization, queue payload, migration cùng package mở rộng đang dùng. Không chép skeleton mới đè bootstrap/config tùy biến.

5. Cổng kiểm tra sau thay đổi

vendor/bin/pint --test
php artisan test
npm run build
node tests/reverb-smoke.mjs
php artisan test --filter=HealthCheckTest
php artisan test --filter=BackupRestoreDrillTest

Suite hiện đã đạt 102 tests/465 assertions; đây là baseline để so sánh, không phải bằng chứng một bản nâng cấp chưa thực hiện đã pass. Kiểm thử thêm user journey ở staging: login/logout, quyền owner, token read/write/revoke, file riêng tư, job, lịch và realtime. Engine database, OS, browser, mail provider hoặc Redis khác local cần kiểm chứng riêng.

Audit xanh không thay test; test xanh không thay review advisory. Nếu audit có cảnh báo, đánh giá package bị ảnh hưởng, đường thực thi và bản vá; không npm audit fix --force rồi chấp nhận mọi major change. Exception tạm thời cần người chịu trách nhiệm, lý do và hạn xử lý.

6. Phát hành và rollback

Tạo artifact từ commit/lockfile đã duyệt, chạy CI thật nếu đã cấu hình, lưu run URL và kết quả staging. Giữ bản release trước có khả năng chạy với schema hiện tại. Quay lockfile về bản cũ không hoàn tác migration, email đã gửi hay job đã chạy. Thay đổi schema theo expand/contract và xem tương thích payload của job còn chờ.

Tài liệu taskflow/deploy/dependency-upgrades.md ghi quy trình áp dụng. Bài tập: chọn một dependency, giải thích vì sao đang có mặt, constraint nào ngăn target và test nào cần bổ sung trước khi update; chỉ thực hiện thay đổi sau review. Bài 37 sẽ đối chiếu tính năng Laravel 13 với dự án đã xây, trước bài tổng hợp toàn khóa.

Tham khảo: Composer CLI, Laravel 13 upgrade guide. Điều hướng: Bài 35 · Lộ trình.

Điều hướng khóa học Laravel 13

Bài trước (35) · Bài sau (37) · Mục lục trọn bộ 37 bài