Composer| Hướng dẫn tạo và publish package
Nếu từ trước đến nay các bạn hay sử dụng composer để quản lý và thêm thư viện (package) để sử dụng trong dự án và bạn thắc mắc là những packages này từ đâu ra ??? và tự mình có thể tạo ra những package như vậy không ??? Vâng ! Bài này chính là giành cho bạn.
Mục lục
1. Giới thiệu
Đầu tiên các packages mà chúng ta hay sử dụng đều thông qua một trang đó là packagist.org đây là nơi quản lý các packages cộng đồng sử dụng, tuy nhiên trang này KHÔNG chứa source của chúng ta mà source vẫn được hosting tại các repositories tại các VCS (Git, BitBucket,…) việc của packagist.org là link đến các repos của bạn và quản lý chúng.
2. Tạo package
2.1 Khai báo thông tin package
Tại terminal của root project bạn gõ lệnh:
// tạo file composer.json composer init
Khi chạy lệnh, composer sẽ bắt bạn nhập vài thông tin cho project, trong đó bạn cần chú ý những thông tin sau:
+ Name gồm “vendor-name”/”package-name” : Tên bạn đặt ở đây chính là tên package mà packagist sử dụng khi mọi người muốn download về.
Như ở trên mình đặt vendor-name là resazipdev và package-name là helper.
Lưu ý: Nếu bạn muốn tạo ra nhiều packages và chung vendor để tiện mọi người khi tìm kiếm package của bạn và khi download về thì những packages mà có chung tên vendor-name sẽ nằm chung vào cùng một thư mục vendor-name thuộc thư mục vendor gốc của composer.
Như hình trên mình có download về 2 package cùng vendor-name là resazipdev thì bên cây thư mục thuộc thư mục vendor bạn sẽ thấy 2 packages helper và testcomposer sẽ cùng nằm trong thư mục resazipdev.
+ Type: chọn là library
+ Minimum Stability: Có 5 lựa chọn (dev, alpha, beta, RC, stable (stable là giá trị mặc định nếu bạn không chọn option nào)).
+ License: nhập là MIT (loại giấy phép được sử dụng tự do nhất)
// Kết quả sau khi điền các thông tin khởi tạo file composer.json
{
"name": "resazipdev/helper",
"type": "library",
"authors": [
{
"name": "resazipdev",
"email": "resazipdev@gmail.com"
}
],
"minimum-stability": "stable",
"license": "MIT",
"require": {}
}
2.2 PSR-4 Autoload
Kế đến ta tiến hành liên kết namespace của package vào đường dẫn của source và ta sẽ dùng psr-4 (psr-4 là một chuẩn của autoload, xem thêm tại đây).
Dễ hình dung thì trong file composer.json mình sẽ viết thêm đoạn này:
"autoload": {
"psr-4": {
"resazipdev\\Helper\\" : "src/"
}
}
Như đoạn code nghĩa là trong package mình sẽ phải tạo folder tên là src tại root và có namespace chung là “resazipdev\Helper\” đồng nghĩa những file php trong folder /src cần phải khai báo có namespace bắt đầu bằng “resazipdev\Helper\”.
Ở đây mình có tạo file /src/Utils.php như sau:
<?php
namespace resazipdev\Helper;
class Utils {
public static function sayHello(){
return "Hello";
}
}
Như trên bạn thấy là mình khai báo namespace cho Utils.php phải bắt đầu là resazipdev\Helper.
Lúc này autoload sẽ tự hiểu là với namespace này thì nó phải load file từ folder nào từ source của mình, ở đây chính là folder /src.
Và file composer.json đến lúc này sẽ như sau:
{
"name": "resazipdev/helper",
"type": "library",
"authors": [
{
"name": "resazipdev",
"email": "resazipdev@gmail.com"
}
],
"minimum-stability": "beta",
"license": "MIT",
"require": {},
"autoload": {
"psr-4": {
"resazipdev\\Helper\\" : "src/"
}
}
}
3. Upload lên VCS
OK sau khi đã tạo được phần package thì bây giờ ta cần đưa chúng lên VCS ở đây mình sẽ sử dụng GitHub.
Lưu ý:
+ Cần phải upload file composer.json này lên luôn rất quan trọng đấy.
+ Repo chứa package cần phải để chế độ là public nếu là private thì bạn cần phải mua gói riêng của packagist.com
Việc đặt tên cho repo trên GitHub thì bạn đặt tên sao cũng được không nhất thiết phải giống như tên đã khai báo trong file composer.json tuy nhiên tốt nhất là bạn nên đặt tên trùng với khi khai báo composer.json :))
4. Đăng ký package với packagist
Bạn truy cập vào packagist.org và đăng ký account để có thể submit package của mình lên.
Sau khi login. trên menu bạn click vào mục Submit để tiến hành đăng ký package.
Ở khung Repository URL (Git/Svn/Hg) bạn nhập vào url repo của package.
Sau khi điền repo url thì nhấn Submit
OK package của mình đã được đăng ký thành công lúc này chúng ta đã có thể download package này về sử dụng được rồi.
Tuy nhiên nó vẫn chưa hoàn thiện, như trên hình ta có 2 vấn đề:
4.1 Khung thông báo: “This package is not auto-updated”
Cái này nghĩa là package của bạn chưa thể tự update nếu bên repo package có thay đổi như là việc cập nhật các phiên bản release chẳng hạn.
Ví dụ: Bên repo package bạn có release thêm một version nữa thì lúc này người dùng vẫn chưa thể cập nhật được version mới này của package, lúc đó bạn phải tự cập nhật thủ công bằng cách sau
Và để thiết lập chế độ auto-updated bạn cần đăng ký WebHook (có nhiệm vụ thông báo cho packagist khi repo bên Git của bạn có thay đổi) làm như sau:
Vào trang quản lý repo package trên GitHub -> chọn Settings -> mục Webhooks -> Add webhook
Tiếp theo bạn điền các thông tin trên theo như mô tả sau:
- Payload URL: https://packagist.org/api/github?username=[your-git-account-name].
- Content Type: application/json.
- Secret: Vào đây -> nhấn Show API Token -> copy token đó và past vào
- Which events…? : Chọn just the push event.
Cuối cùng là quay về trang quản lý package bên packagist và nhấn update.
Ok vậy là xong phần thiết lập chế độ auto-updated cho package.
4.2 Version release của package
Mặc định repo của ta lúc nào cũng sẽ có một nhánh chính thường thì nó sẽ tên là main hay master gì đó (mình có thể change name nhánh chính này được) và packagist sẽ dùng tên nhánh chính này để làm version default của package ở chế độ dev và có tên là dev-main (main chính là default branch của mình, nếu tên nhánh của bạn là master thì sẽ là dev-master).
Ok nhưng mà nó có nhiệm vụ là gì ??? À nó sẽ dùng để xác định version package mà người dùng sẽ tải về sử dụng. Cụ thể ở đây là nó liên quan đến giá trị bạn khai báo “minimum-stability”:”dev / alpha / beta / RC / stable” trong file composer.json hay như khi tải package về ta sẽ xác định luôn version cần tải như
composer require resazipdev/helper:^v1.0
Với ví dụ trong bài này thì hiện tại repo của mình chưa release bất kỳ version nào
Nên nó chỉ có version default ở chế độ dev là dev-main, vì vậy khi người dùng muốn tải package này thì trong composer.json của bạn cần khai báo “minimum-stability”: “dev” hoặc nếu chỉ muốn áp dụng riêng stability cho package nào đó thì gõ
// chỉ lấy các version là chế độ dev của package composer require resazipdev/helper@dev
Lúc này nó sẽ tải phiên bản dev-main về
Nếu bạn set minimum-stability là stable thì nó sẽ báo không có version phù hợp để tải về
Could not find a version of package resazipdev/helper matching your minimum-stability (stable). Require it with an explicit version constraint allowing its desired stability.
Vậy để package của bạn trở thành stable thì như thế nào ?
Bên GitHub bạn cần tạo release version và đặt tên cho nó kiểu như v1.0 hay v.1.1.0 gì đấy bạn có thể tham khảo cách đặt tên version tại đây
Ở đây mình có release version với name là v1.0
Sau đó quay lại trang packagist và nhấn update nếu có auto-update rồi không cần thao tác này. Sau đó package của bạn sẽ xuất hiện như thế này
OK, lúc này nếu ngươi dùng set minimum-stability là stable thì đã có thể tải phiên bản v1.0 sau này nếu bạn có release nhiều version nữa thì cứ làm những bước này là ok.
Trong bài khác mình sẽ nói rõ hơn về minimum-stability sau 🙂
5. Gọi và sử dụng package
Ở ứng dụng người dùng sau khi tải package về ta sẽ có file composer.json như sau:
{
"name": "resazipdev/use-composer",
"type": "project",
"minimum-stability": "stable",
"require": {
"resazipdev/helper": "^1.0"
}
}
Package sau khi tải về nằm trong folder vendor
Để chạy, ở file chính thường là index.php bạn cần phải include file autoload.php từ folder vendor trước tiên
require_once 'vendor/autoload.php'; use resazipdev\Helper\Utils; echo Utils::sayHello();
Và chạy xem kết quả
Tham khảo
https://www.w3resource.com/php/composer/create-publish-and-use-your-first-composer-package.php
https://viblo.asia/p/psr-0-vs-psr-4-cac-chuan-autoload-file-924lJDjNKPM
