Login

Composer và Packagist: quản lý thư viện PHP đúng cách

  • author-image

    Nguyễn Đình Cường

  • blog-tag
  • blog-comment 0 comment
  • created-date 09 Nov, 2026
blog-thumbnail

Hầu như mọi dự án PHP hiện đại đều dựa vào thư viện của người khác. Composer là công cụ giúp bạn khai báo, cài đặt và cập nhật chúng một cách có kiểm soát. Hiểu vài khái niệm cốt lõi sẽ giúp bạn tránh được những lỗi khó chịu khi làm việc nhóm hoặc triển khai.

Composer làm gì cho bạn?

Composer là trình quản lý phụ thuộc: bạn nói dự án cần thư viện nào, nó tải về cùng các thư viện mà thư viện đó cần, sắp xếp phiên bản tương thích và tạo cơ chế tự động nạp class. Nguồn gói phổ biến nhất là Packagist, kho công khai mà Composer tra cứu mặc định.

composer initcomposer require guzzlehttp/guzzlecomposer require --dev phpunit/phpunit

Lệnh thứ ba thêm gói vào nhóm require-dev, tức chỉ dùng khi phát triển và kiểm thử, không cần ở production.

composer.json và composer.lock

Hai file này hay bị nhầm lẫn:

  • composer.json: khai báo ý định, ví dụ "tôi cần Guzzle phiên bản 7 trở lên, dưới 8".
  • composer.lock: ghi lại phiên bản chính xác đã được cài, kèm mã băm. Đây là bản chụp để mọi người và mọi máy chủ dùng cùng một bộ phiên bản.

Quy tắc quan trọng: hãy commit cả hai file vào Git (với ứng dụng, không phải thư viện), và trên server luôn dùng composer install để cài đúng phiên bản trong file lock. Lệnh composer update mới là lệnh thay đổi phiên bản, nên chỉ chạy có chủ đích trên máy phát triển rồi kiểm thử lại.

{  "require": {    "php": "^8.2",    "guzzlehttp/guzzle": "^7.8"  },  "autoload": {    "psr-4": { "App\\": "src/" }  }}

Ký hiệu phiên bản

Phiên bản theo dạng chính.phụ.vá (semantic versioning). Một số ký hiệu hay gặp:

  • ^7.8: cho phép nâng đến trước 8.0 (không phá vỡ tương thích theo quy ước).
  • ~7.8.1: chỉ cho phép nâng bản vá, tức dưới 7.9.
  • 7.8.1: ghim đúng một phiên bản.

Dùng ^ là lựa chọn phổ biến và cân bằng. Nhưng hãy nhớ quy ước chỉ là lời hứa của tác giả thư viện, nên vẫn cần kiểm thử sau khi cập nhật.

Autoload PSR-4

Thay vì viết require cho từng file, bạn ánh xạ namespace tới thư mục. Với cấu hình ở trên, class App\Service\Mailer được nạp từ src/Service/Mailer.php. Sau khi sửa phần autoload, chạy composer dump-autoload. Ở production có thể dùng composer install --no-dev --optimize-autoloader để bỏ gói chỉ dành cho phát triển và tăng tốc nạp class.

require __DIR__ . '/vendor/autoload.php';use App\Service\Mailer;$mailer = new Mailer();

Giữ phụ thuộc an toàn

  • Chạy composer audit để kiểm tra các lỗ hổng đã biết trong thư viện đang dùng.
  • Chỉ thêm thư viện thật sự cần; mỗi gói thêm là thêm bề mặt rủi ro và việc phải bảo trì.
  • Xem xét độ phổ biến, tần suất cập nhật và người duy trì trước khi dùng gói mới.
  • Không commit thư mục vendor vào Git; nó được sinh ra từ file lock.
  • Dùng composer outdated để biết gói nào đã có bản mới, cập nhật định kỳ thay vì để dồn lại nhiều năm.

Khi gặp xung đột phiên bản

Thông báo "Your requirements could not be resolved" nghĩa là các gói đòi hỏi phiên bản không tương thích với nhau. Dùng composer why-not tên/gói phiên-bản để biết điều gì đang cản trở, và composer why tên/gói để biết gói nào kéo thư viện đó vào. Thông thường cách giải quyết là nâng đồng thời một nhóm gói liên quan hoặc chọn phiên bản PHP phù hợp. Tránh dùng cờ bỏ qua yêu cầu nền tảng trừ khi bạn hiểu rõ hậu quả.

Composer trong quy trình triển khai

Một quy trình triển khai ổn định thường có các bước: kéo code mới, chạy composer install --no-dev --optimize-autoloader --no-interaction, chạy migration, xóa và dựng lại cache cấu hình. Vì file lock đã cố định phiên bản, server production sẽ có đúng những gói mà bạn đã kiểm thử ở máy mình. Nếu bạn dùng Docker, hãy sao chép composer.json và composer.lock trước rồi chạy cài đặt, sau đó mới sao chép phần còn lại của code; nhờ cơ chế lớp (layer cache) của Docker, các lần build sau sẽ không phải cài lại thư viện khi chỉ code ứng dụng thay đổi.

Tạo gói riêng của bạn

Khi có đoạn code dùng lại ở nhiều dự án, bạn có thể đóng gói nó. Chỉ cần một file composer.json có tên gói dạng ten-ban/ten-goi, khai báo autoload, và đẩy repository lên GitHub rồi đăng ký trên Packagist. Với gói nội bộ, bạn có thể trỏ Composer vào repository riêng bằng mục repositories, nhờ vậy không cần công khai mã nguồn mà vẫn tái sử dụng được giữa các dự án của công ty.

Kết luận

Hãy ghi nhớ ba điều: commit file lock, dùng install trên server và update có chủ đích trên máy phát triển, và kiểm tra bảo mật phụ thuộc định kỳ. Có thói quen này, việc triển khai của bạn sẽ ổn định và dễ đoán hơn rất nhiều.

Khi cần một lộ trình học có hệ thống, bạn có thể tham khảo khóa học trên codebem.com.

author_photo
Nguyễn Đình Cường

0 comment