iT邦幫忙

第 12 屆 iThome 鐵人賽

DAY 14
0
Software Development

PHP 大師之路 - 開源的技術淬練系列 第 14

Day 14 - 發佈 Composer 套件的事前準備

  • 分享至 

  • xImage
  •  

首先,你必須有一個 GitHub 帳號,如果沒有的話快去申請一個GitHub 帳號,並新增一個儲存庫 (repository)。

然後,你也必須有一個 Packagist 帳號,這是把我們的 PHP 作品發佈成 Composer 套件的地方,以供大家使用 Composer 指令下載、管理專案套件。如果沒有帳號的話,快去申請一個 Packagist 帳號。

申請帳號:

命名訣竅

使用者名稱 (username) 及儲存庫的命名務必簡短好記。因為 GitHub 把這兩者當成標題前輟,接著是儲存庫的介紹文章。標題長度超過 60 個字元,Google 就會顯示為「...」,好好發揮一些 SEO 知識在命名及介紹文字上吧。好的標題命名會讓你的作品被搜尋到的機率增高,搜尋排名較前,星星數自然會自己慢慢成長。

範例:

InGlZ4Q.png

關鍵字塞好塞滿,不廢話。XD

建立一個 GitHub 儲存庫

G5CrT4H.png

這個範例中,筆者建立了一個儲存庫,名為「ironman」,打上介紹,選擇公開 (public),授權條款是一門學問,但筆者通常會選擇 MIT,不是「Made in Taiwan」唷!而是一個相對寬鬆,歡迎大家使用修改不限用途的授權條款。筆者認為,既然有分享的心,就不要計較。如果有人拿它發展成受歡迎的分支,在商業上取得成功,身為草創者,也是與有榮焉呢。

9s8kWHZ.png

建立之後,這個新的儲存庫空空如也。

註:如果是 Git 新手,可以下載使用 Sourcetree 這套免費的 GUI 工具來管理你的儲存庫,是比較簡單的選擇。

送出套件申請

送出套件申請的「Submit」連結就在上方的選單列。

2dpmQoY.png

只要輸出剛剛建立的 GitHub 儲存庫的網址,Packagist 就會檢查該儲存庫是否有 composer.json 這個檔案。如果沒有的話,會貼心提醒。

ObM6TFh.png

建立 composer.json

這個檔案是 PHP 套件的設定檔,以其它程式語言例如 NodeJS 來比喻,等同於 package.json 的地位。composer.json 包含了一切所需的資訊,例如套件名稱、介紹、依賴的套件、開發環境所需的套件等等。

欄位結構

在 Composer 官方網站的文件有 composer.json 的欄位結構說明文件,以下的範例是筆者作品使用的設定。

{
    "name": "shieldon/psr-http",
    "description": "HTTP implementation for PSR standard.",
    "keywords": ["php-http", "psr7", "psr-15", "psr-17"],
    "homepage": "https://github.com/terrylinooo/psr-http",
    "license": "MIT",
    "authors": [
        {
            "name": "Terry Lin",
            "email": "contact@terryl.in",
            "homepage": "https://terryl.in",
            "role": "Developer"
        }
    ],
    "minimum-stability": "stable",
    "require": {
        "php": ">=7.1.0",
        "psr/http-factory": "^1.0",
        "psr/http-message": "^1.0",
        "psr/http-server-handler": "^1.0",
        "psr/http-server-middleware": "^1.0"
    },
    "require-dev": {
        "phpunit/phpunit": "^7"
    },
    "autoload": {
        "psr-4": {
            "Shieldon\\Psr7\\": "src/Psr7",
            "Shieldon\\Psr15\\": "src/Psr15",
            "Shieldon\\Psr17\\": "src/Psr17"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Shieldon\\Test\\Psr7\\": "tests/Psr7",
            "Shieldon\\Test\\Psr15\\": "tests/Psr15",
            "Shieldon\\Test\\Psr17\\": "tests/Psr17"
        }
    },
    "config": {
        "process-timeout": 0,
        "sort-packages": true
    },
    "scripts": {
        "test": "php vendor/phpunit/phpunit/phpunit"
    }
}

雖然官方文件提供的欄位很多,但實務最常用的如下:

name

套件名稱,由供應商名稱與專案名稱組合,用 /。以本範例來說,名稱為 shieldon/psr-http,在使用 Composer 下載時的指令為:

composer require shieldon/psr-http

請用純寫小字母(可含有 -., _),取一個帥帥的套件名稱吧。

description

套件的介紹文字。會顯示在 Packagist 網站上你的套件頁面。

keywords

關聯的關鍵字。會變成Packagist 網站上的標籤連結。

homepage

套件的首頁。一般來說,放專案網站的網址或 GitHub 儲存庫的網址。

license

授權條款。

authors

作者群。你可以把主要協力者加進來。

minimum-stability

比較重要的設定。設為 stable(預設值),用戶下 require 指令只會下載目前釋出版本,而不是直接拉 master 分支的程式碼。如果 tag 中的版號含有 devbetarcalpha 字串,就會略過,只下載穩定版本。

選項:dev, alpha, beta, RC, and stable.

require

本套件依賴的套件。

require-dev

開發模式所依賴的套件。當 composer 指令列有 --dev 這個參數,即會安裝此列表的依賴套件。
註:--dev 參數已棄用。現在 Composer 預設會安裝 require-dev 裡定義的套件。

範例:

composer install --dev

autoload

自動載入的設定。本例為指定 PSR-4 載入的基本目錄。

範例:

"autoload": {
    "psr-4": {
        "Shieldon\\Psr7\\": "src/Psr7",
        "Shieldon\\Psr15\\": "src/Psr15",
        "Shieldon\\Psr17\\": "src/Psr17"
    }
},

這個例子表示當使用者準備實例化類別時,依照這些命名空間前輟,自動載入設定的基本目錄下的檔案。例如:

new \Shieldon\Psr7\ServerRequest();

則會自動查找並載入 src/Psr7/ServerRequest.php 這個檔案。
詳細的說明請參考筆者在 Day 12 的「PHP 自動載入機制:PSR-4」文章有更詳細的解說。

autoload-dev

自動載入的設定。本例為指定 PSR-4 載入的基本目錄。

config

設定值。更多細項設定見官方文件

scripts

很實用的欄位,最常用來自訂命令。

範例:

"scripts": {
    "test": "php vendor/phpunit/phpunit/phpunit"
}

使用

composer test

等於

php vendor/phpunit/phpunit/phpunit

再次發佈

前次因為沒 composer.json 所以發佈失敗。這次傳上去了,再送出申請。

內容:

{
    "name": "ithelp/ironman",
    "description": "這是第 12 屆 IT 邦幫忙鐵人賽的範例啦。",
    "keywords": ["ironman", "game"],
    "homepage": "https://github.com/terrylinoo/ironman",
    "license": "MIT",
    "authors": [
        {
            "name": "Terry Lin",
            "email": "contact@terryl.in",
            "homepage": "https://terryl.in",
            "role": "Developer"
        }
    ],
    "minimum-stability": "stable",
    "require": {
        "php": ">=7.1.0"
    },
    "require-dev": {
        "phpunit/phpunit": "^7"
    },
    "autoload": {
        "psr-4": {
            "ItHelp\\": "src"
        }
    }
}

已經可以透過 Composer 指令下載。

1tazMzX.png

範例程式碼:

此範例的套件頁面網址:

測試剛剛的套件:

YETexob.png

就這樣......一個 PHP Composer 套件完成了。(笑)

如果要讓你的 GitHub 專案一發佈新版號時,Packagist 即時連動更新的話,請記得進個人資料的設定頁面,和按下和 GitHub 連結的按紐唷!

總結

今天介紹的是發佈套件的事前準備。只要專案儲存庫的根目錄有 composer.json 這個檔案並有適當的設定,Packagist 就會將 GitHub 專案連結囉!

歡迎成為開放源碼作者群。

我們明天見。


本文同步更新於 TerryL 部落格 Day 14 - 發佈 Composer 套件的事前準備,歡迎前往討論。


上一篇
Day 13 - PHP HTTP 通訊相關介面:PSR-7, PSR-15, PSR-17
下一篇
Day 15 - PHP 套件設計實戰 (1) 決定主題
系列文
PHP 大師之路 - 開源的技術淬練30
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言