函式庫#

本章會告訴你如何透過 Composer 讓你的函式庫可安裝。

每個專案是一個套件#

只要你在目錄中有一個 composer.json,該目錄就是一個套件。 當你添加一個 require 到一個專案,你正在讓一個套件依賴其他套件。 你的專案和函式庫唯一的不同之處, 在於你的專案是一個未命名的套件。

為了要讓套件可安裝,你需要給它一個名稱。你透過在 composer.json 添加 name 屬性來達成:

{
    "name": "acme/hello-world",
    "require": {
        "monolog/monolog": "1.0.*"
    }
}

在這個情況下,專案名稱是 acme/hello-worldacme 是 vendor 名稱。提供一個 vendor 名稱是強制性的。

注意: 如果你不知道要用什麼做為 vendor 名稱,你的 GitHub 使用者名稱通常是一個不錯的選擇。雖然套件名稱不分大小寫, 慣例是全小寫字母然後用連字符對文字分隔。

Library Versioning#

In the vast majority of cases, you will be maintaining your library using some sort of version control system like git, svn, hg or fossil. In these cases, Composer infers versions from your VCS and you should not specify a version in your composer.json file. (See the Versions article to learn about how Composer uses VCS branches and tags to resolve version constraints.)

If you are maintaining packages by hand (i.e., without a VCS), you'll need to specify the version explicitly by adding a version value in your composer.json file:

{
    "version": "1.0.0"
}

Note: When you add a hardcoded version to a VCS, the version will conflict with tag names. Composer will not be able to determine the version number.

VCS Versioning#

Composer uses your VCS's branch and tag features to resolve the version constraints you specify in your require field to specific sets of files. When determining valid available versions, Composer looks at all of your tags and branches and translates their names into an internal list of options that it then matches against the version constraint you provided.

For more on how Composer treats tags and branches and how it resolves package version constraints, read the versions article.

鎖檔案#

如果你願意,你可以為你的函式庫 commit composer.lock 檔案。 這有助於你的團隊始終針對相同的依賴套件版本做測試。 然而,這個鎖檔案在其他依賴它的專案不會造成任何影響。 它只在主要專案有效果。

如果你不希望 commit 該鎖檔案而且你使用 git,添加它到 .gitignore

發表到一個 VCS#

一旦你讓一個 VCS 儲存庫(版本控制系統,例如 git)包含一個 composer.json 檔案,你的函式庫就已經可以讓 composer 安裝。 在這個範例中,我們會在 GitHub 的 github.com/username/hello-world 發表 acme/hello-world 函式庫。

現在,為了測試安裝 acme/hello-world 套件,我們在本地建立一個新專案。 我們會叫它 acme/blog。這個部落格會依賴 acme/hello-world,而它又依賴於 monolog/monolog。 我們可以透過在某地建立一個新的 blog 目錄,包含一個 composer.json,來完成它:

{
    "name": "acme/blog",
    "require": {
        "acme/hello-world": "dev-master"
    }
}

在這個情況下,名稱是不需要的,因為我們不想要發表 blog 為一個函式庫。 它被添加在這裡以闡明哪個 composer.json 會被描述。

現在我們需要告訴 blog 應用程式在哪裡可以找到 hello-world 依賴套件。 我們透過添加一個套件儲存庫規格到 blog 的 composer.json 來辦到:

{
    "name": "acme/blog",
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/username/hello-world"
        }
    ],
    "require": {
        "acme/hello-world": "dev-master"
    }
}

更多關於套件儲存庫如何運作及其他可用類型的細節, 詳見 儲存庫

就這樣。現在你可以透過執行 Composer 的 install 命令來安裝依賴套件!

回顧: 任何包含 composer.json 的 git/svn/hg/fossil 儲存庫可以透過在 require 欄位指定套件儲存庫及宣告依賴,來添加到你的專案。

發表到 packagist#

好了,現在你可以發表套件。但每次指定 VCS 儲存庫很麻煩。你不希望強迫所有使用者這樣做。

你可能已經注意到的另一件事是,我們沒有為 monolog/monolog 指定一個套件儲存庫。那是怎麼運作的?答案是 Packagist

Packagist 是針對 Composer 主要的套件儲存庫, 而預設它是啟用的。任何發表在 Packagist 上的可以自動透過 Composer 使用。因為 Monolog 在 Packagist 上, 我們可以依賴它而不必指定任何額外的儲存庫。

如果我們想與全世界分享 hello-world,我們也會在 Packagist 上發表它。這樣做是非常容易的。

You simply visit Packagist and hit the "Submit" button. This will prompt you to sign up if you haven't already, and then allows you to submit the URL to your VCS repository, at which point Packagist will start crawling it. Once it is done, your package will be available to anyone!

基本使用 | 命令列介面

發現錯字?在這個文件中有些錯誤?只要 fork 並編輯 它!