閱讀(5.3k) 書簽贊(0) 我要糾錯

Composer 架構

2018-09-28 20:22 更新

composer.json 架構

本章將解釋所有在 composer.json 中可用的字段。

JSON schema

我們有一個 JSON schema 格式化文檔，它也可以被用來驗證你的 composer.json 文件。事實上，它已經被 validate 命令所使用。你可以在這里找到它： res/composer-schema.json.

Root 包

“root 包”是指由 composer.json 定義的在你項目根目錄的包。這是 composer.json 定義你項目所需的主要條件。（簡單的說，你自己的項目就是一個 root 包）

某些字段僅適用于“root 包”上下文。 config 字段就是其中一個例子。只有“root 包”可以定義。在依賴包中定義的 config 字段將被忽略，這使得 config 字段只有“root 包”可用（root-only）。

如果你克隆了其中的一個依賴包，直接在其上開始工作，那么它就變成了“root 包”。與作為他人的依賴包時使用相同的 composer.json 文件，但上下文發(fā)生了變化。

注意： 一個資源包是不是“root 包”，取決于它的上下文。例：如果你的項目依賴 monolog 庫，那么你的項目就是“root 包”。但是，如果你從 GitHub 上克隆了 monolog 為它修復 bug，那么此時 monolog 就是“root 包”。

屬性

包名 name

包的名稱，它包括供應商名稱和項目名稱，使用 / 分隔。

例：

monolog/monolog
igorw/event-source

對于需要發(fā)布的包（庫），這是必須填寫的。

描述 description

一個包的簡短描述。通常這個最長只有一行。

對于需要發(fā)布的包（庫），這是必須填寫的。

版本 version

version 不是必須的，并且建議忽略（見下文）。

它應該符合 'X.Y.Z' 或者 'vX.Y.Z' 的形式， -dev、-patch、-alpha、-beta 或 -RC 這些后綴是可選的。在后綴之后也可以再跟上一個數字。

例：

1.0.0
1.0.2
1.1.0
0.2.5
1.0.0-dev
1.0.0-alpha3
1.0.0-beta2
1.0.0-RC5

通常，我們能夠從 VCS (git, svn, hg) 的信息推斷出包的版本號，在這種情況下，我們建議忽略 version。

注意： Packagist 使用 VCS 倉庫，因此 version 定義的版本號必須是真實準確的。自己手動指定的 version，最終有可能在某個時候因為人為錯誤造成問題。

安裝類型 type

包的安裝類型，默認為 library。

包的安裝類型，用來定義安裝邏輯。如果你有一個包需要一個特殊的邏輯，你可以設定一個自定義的類型。這可以是一個 symfony-bundle，一個 wordpress-plugin 或者一個 typo3-module。這些類型都將是具體到某一個項目，而對應的項目將要提供一種能夠安裝該類型包的安裝程序。

composer 原生支持以下4種類型：

library: 這是默認類型，它會簡單的將文件復制到 vendor 目錄。
project: 這表示當前包是一個項目，而不是一個庫。例：框架應用程序 Symfony standard edition，內容管理系統 SilverStripe installer 或者完全成熟的分布式應用程序。使用 IDE 創(chuàng)建一個新的工作區(qū)時，這可以為其提供項目列表的初始化。
metapackage: 當一個空的包，包含依賴并且需要觸發(fā)依賴的安裝，這將不會對系統寫入額外的文件。因此這種安裝類型并不需要一個 dist 或 source。
composer-plugin: 一個安裝類型為 composer-plugin 的包，它有一個自定義安裝類型，可以為其它包提供一個 installler。詳細請查看自定義安裝類型。

僅在你需要一個自定義的安裝邏輯時才使用它。建議忽略這個屬性，采用默認的 library。

關鍵字 `keywords`

該包相關的關鍵詞的數組。這些可用于搜索和過濾。

實例：

logging
events
database
redis
templating

可選。

項目主頁 homepage

該項目網站的 URL 地址。

可選。

版本發(fā)布時間 time

版本發(fā)布時間。

必須符合 YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS 格式。

可選。

許可協議 license

包的許可協議，它可以是一個字符串或者字符串數組。

最常見的許可協議的推薦寫法（按字母排序）：

Apache-2.0
BSD-2-Clause
BSD-3-Clause
BSD-4-Clause
GPL-2.0
GPL-2.0+
GPL-3.0
GPL-3.0+
LGPL-2.1
LGPL-2.1+
LGPL-3.0
LGPL-3.0+
MIT

可選，但強烈建議提供此內容。更多許可協議的標識符請參見 SPDX Open Source License Registry。

對于閉源軟件，你必須使用 "proprietary" 協議標識符。

一個例：

{
    "license": "MIT"
}

對于一個包，當允許在多個許可協議間進行選擇時（"disjunctive license"），這些協議標識符可以被指定為數組。

多協議的一個例：

{
    "license": [
       "LGPL-2.1",
       "GPL-3.0+"
    ]
}

另外它們也可以由 "or" 分隔，并寫在括號中：

{
    "license": "(LGPL-2.1 or GPL-3.0+)"
}

同樣，當有多個許可協議需要結合使用時（"conjunctive license"），它們應該被 "and" 分隔，并寫在括號中。

作者 authors

包的作者。這是一個對象數組。

這個對象必須包含以下屬性：

name: 作者的姓名，通常使用真名。
email: 作者的 email 地址。
homepage: 作者主頁的 URL 地址。
role: 該作者在此項目中擔任的角色（例：開發(fā)人員或翻譯）。

一個實例：

{
    "authors": [
        {
            "name": "Nils Adermann",
            "email": "naderman@naderman.de",
            "homepage": "http://www.naderman.de",
            "role": "Developer"
        },
        {
            "name": "Jordi Boggiano",
            "email": "j.boggiano@seld.be",
            "homepage": "http://seld.be",
            "role": "Developer"
        }
    ]
}

可選，但強烈建議提供此內容。

支持 support

獲取項目支持的向相關信息對象。

這個對象必須包含以下屬性：

email: 項目支持 email 地址。
issues: 跟蹤問題的 URL 地址。
forum: 論壇地址。
wiki: Wiki 地址。
irc: IRC 聊天頻道地址，類似于 irc://server/channel。
source: 網址瀏覽或下載源。

一個實例：

{
    "support": {
        "email": "support@example.org",
        "irc": "irc://irc.freenode.org/composer"
    }
}

可選。

Package links

下面提到的所有對象，都應該是包名到版本的映射對象。

實例：

{
    "require": {
        "monolog/monolog": "1.0.*"
    }
}

所有的這些都是可選的。

require 和 require-dev 還支持穩(wěn)定性標簽（@，僅針對“root 包”）。這允許你在 minimum-stability設定的范圍外做進一步的限制或擴展。例：如果你想允許依賴一個不穩(wěn)定的包，你可以在一個包的版本約束后使用它，或者是一個空的版本約束內使用它。

實例：

{
    "require": {
        "monolog/monolog": "1.0.*@beta",
        "acme/foo": "@dev"
    }
}

如果你的依賴之一，有對另一個不穩(wěn)定包的依賴，你最好在 require 中顯示的定義它，并帶上足夠詳細的穩(wěn)定性標識。

實例：

{
    "require": {
        "doctrine/doctrine-fixtures-bundle": "dev-master",
        "doctrine/data-fixtures": "@dev"
    }
}

require 和 require-dev 還支持對 dev（開發(fā)）版本的明確引用（即：版本控制系統中的提交編號 commit），以確保它們被鎖定到一個給定的狀態(tài)，即使你運行了更新命令。你只需要明確一個開發(fā)版本號，并帶上諸如 #<ref> 的標識。

實例：

{
    "require": {
        "monolog/monolog": "dev-master#2eb0c0978d290a1c45346a1955188929cb4e5db7",
        "acme/foo": "1.0.x-dev#abc123"
    }
}

注意： 雖然這有時很方便，但不應該長期在你的包中使用，因為它有一個技術上的限制。 composer.json 將仍然在哈希值之前指定的分支名稱讀取元數據，正因為如此，在某些情況下，它不會是一個實用的解決方法，如果可能，你應該總是嘗試切換到擁有標簽的版本。

它也可以應用于行內別名，這樣它將匹配一個約束，否則不會。更多信息請參考別名。

require

必須的軟件包列表，除非這些依賴被滿足，否則不會完成安裝。

require-dev (root-only)

這個列表是為開發(fā)或測試等目的，額外列出的依賴。“root 包”的 require-dev 默認是會被安裝的。然而 install 或 update 支持使用 --no-dev 參數來跳過 require-dev 字段中列出的包。

conflict

此列表中的包與當前包的這個版本沖突。它們將不允許同時被安裝。

請注意，在 conflict 中指定類似于 <1.0, >= 1.1 的版本范圍時，這表示它與小于1.0 并且同時大等于1.1的版本沖突，這很可能不是你想要的。在這種情況下你可能想要表達的是 <1.0 | >= 1.1 。

replace

這個列表中的包將被當前包取代。這使你可以 fork 一個包，以不同的名稱和版本號發(fā)布，同時要求依賴于原包的其它包，在這之后依賴于你 fork 的這個包，因為它取代了原來的包。

這對于創(chuàng)建一個內部包含子包的主包也非常的有用。例如 symfony/symfony 這個主包，包含了所有 Symfony 的組件，而這些組件又可以作為單獨的包進行發(fā)布。如果你 require 了主包，那么它就會自動完成其下各個組件的任務，因為主包取代了子包。

注意，在使用上述方法取代子包時，通常你應該只對子包使用 self.version 這一個版本約束，以確保主包僅替換掉子包的準確版本，而不是任何其他版本。

provide

List of other packages that are provided by this package. This is mostly useful for common interfaces. A package could depend on some virtual logger package, any library that implements this logger interface would simply list it in provide.

suggest

建議安裝的包，它們增強或能夠與當前包良好的工作。這些只是信息，并顯示在依賴包安裝完成之后，給你的用戶一個建議，他們可以添加更多的包。

格式如下，版本約束變成了描述信息。

實例：

{
    "suggest": {
        "monolog/monolog": "Allows more advanced logging of the application flow"
    }
}

autoload

PHP autoloader 的自動加載映射。

Currently PSR-0 autoloading, PSR-4 autoloading, classmap generation and files includes are supported. PSR-4 is the recommended way though since it offers greater ease of use (no need to regenerate the autoloader when you add classes).

PSR-4

Under the psr-4 key you define a mapping from namespaces to paths, relative to the package root. When autoloading a class like Foo\\Bar\\Baz a namespace prefix Foo\\ pointing to a directory src/ means that the autoloader will look for a file named src/Bar/Baz.php and include it if present. Note that as opposed to the older PSR-0 style, the prefix (Foo\\) is not present in the file path.

Namespace prefixes must end in \\ to avoid conflicts between similar prefixes. For example Foo would match classes in the FooBar namespace so the trailing backslashes solve the problem: Foo\\ and FooBar\\ are distinct.

The PSR-4 references are all combined, during install/update, into a single key => value array which may be found in the generated file vendor/composer/autoload_psr4.php.

Example:

{
    "autoload": {
        "psr-4": {
            "Monolog\\": "src/",
            "Vendor\\Namespace\\": ""
        }
    }
}

If you need to search for a same prefix in multiple directories, you can specify them as an array as such:

{
    "autoload": {
        "psr-4": { "Monolog\\": ["src/", "lib/"] }
    }
}

If you want to have a fallback directory where any namespace will be looked for, you can use an empty prefix like:

{
    "autoload": {
        "psr-4": { "": "src/" }
    }
}

PSR-0

在 psr-0 key 下你定義了一個命名空間到實際路徑的映射（相對于包的根目錄）。注意，這里同樣支持 PEAR-style 方式的約定（與命名空間不同，PEAR 類庫在類名上采用了下劃線分隔）。

請注意，命名空間的申明應該以 \\ 結束，以確保 autoloader 能夠準確響應。例： Foo 將會與 FooBar 匹配，然而以反斜杠結束就可以解決這樣的問題， Foo\\ 和 FooBar\\ 將會被區(qū)分開來。

在 install/update 過程中，PSR-0 引用都將被結合為一個單一的鍵值對數組，存儲至 vendor/composer/autoload_namespaces.php 文件中。

實例：

{
    "autoload": {
        "psr-0": {
            "Monolog\\": "src/",
            "Vendor\\Namespace\\": "src/",
            "Vendor_Namespace_": "src/"
        }
    }
}

如果你需要搜索多個目錄中一個相同的前綴，你可以將它們指定為一個數組，例：

{
    "autoload": {
        "psr-0": { "Monolog\\": ["src/", "lib/"] }
    }
}

PSR-0 方式并不僅限于申明命名空間，也可以是精確到類級別的指定。這對于只有一個類在全局命名空間的類庫是非常有用的（如果 php 源文件也位于包的根目錄）。例如，可以這樣申明：

{
    "autoload": {
        "psr-0": { "UniqueGlobalClass": "" }
    }
}

如果你想設置一個目錄作為任何命名空間的備用目錄，你可以使用空的前綴，像這樣：

{
    "autoload": {
        "psr-0": { "": "src/" }
    }
}

Classmap

classmap 引用的所有組合，都會在 install/update 過程中生成，并存儲到 vendor/composer/autoload_classmap.php 文件中。這個 map 是經過掃描指定目錄（同樣支持直接精確到文件）中所有的 .php 和 .inc 文件里內置的類而得到的。

你可以用 classmap 生成支持支持自定義加載的不遵循 PSR-0/4 規(guī)范的類庫。要配置它指向需要的目錄，以便能夠準確搜索到類文件。

實例：

{
    "autoload": {
        "classmap": ["src/", "lib/", "Something.php"]
    }
}

Files

如果你想要明確的指定，在每次請求時都要載入某些文件，那么你可以使用 'files' autoloading。通常作為函數庫的載入方式（而非類庫）。

實例：

{
    "autoload": {
        "files": ["src/MyLibrary/functions.php"]
    }
}

autoload-dev (root-only)

This section allows to define autoload rules for development purposes.

Classes needed to run the test suite should not be included in the main autoload rules to avoid polluting the autoloader in production and when other people use your package as a dependency.

Therefore, it is a good idea to rely on a dedicated path for your unit tests and to add it within the autoload-dev section.

Example:

{
    "autoload": {
        "psr-4": { "MyLibrary\\": "src/" }
    },
    "autoload-dev": {
        "psr-4": { "MyLibrary\\Tests\\": "tests/" }
    }
}

include-path

不建議：這是目前唯一支持傳統項目的做法，所有新的代碼都建議使用自動加載。這是一個過時的做法，但 Composer 將仍然保留這個功能。

一個追加到 PHP include_path 中的列表。

實例：

{
    "include-path": ["lib/"]
}

可選。

target-dir

DEPRECATED: This is only present to support legacy PSR-0 style autoloading, and all new code should preferably use PSR-4 without target-dir and projects using PSR-0 with PHP namespaces are encouraged to migrate to PSR-4 instead.

定義當前包安裝的目標文件夾。

若某個包的根目錄，在它申明的命名空間之下，將不能正確的使用自動加載。而 target-dir 解決了這個問題。

Symfony 就是一個例子。它有一些獨立的包作為組件。Yaml 組件就放在 Symfony\Component\Yaml 目錄下，然而這個包的根目錄實際上是 Yaml。為了使自動加載成為可能，我們需要確保它不會被安裝到 vendor/symfony/yaml，而是安裝到 vendor/symfony/yaml/Symfony/Component/Yaml，從而使 Symfony 定義的 autoloader 可以從 vendor/symfony/yaml 加載它。

要做到這一點 autoload 和 target-dir 應該定義如下：

{
    "autoload": {
        "psr-0": { "Symfony\\Component\\Yaml\\": "" }
    },
    "target-dir": "Symfony/Component/Yaml"
}

可選。

minimum-stability (root-only)

這定義了通過穩(wěn)定性過濾包的默認行為。默認為 stable（穩(wěn)定）。因此如果你依賴于一個 dev（開發(fā)）包，你應該明確的進行定義。

對每個包的所有版本都會進行穩(wěn)定性檢查，而低于 minimum-stability 所設定的最低穩(wěn)定性的版本，將在解決依賴關系時被忽略。對于個別包的特殊穩(wěn)定性要求，可以在 require 或 require-dev 中設定（請參考 Package links）。

可用的穩(wěn)定性標識（按字母排序）：dev、alpha、beta、RC、stable。

prefer-stable (root-only)

當此選項被激活時，Composer 將優(yōu)先使用更穩(wěn)定的包版本。

使用 "prefer-stable": true 來激活它。

repositories (root-only)

使用自定義的包資源庫。

默認情況下 composer 只使用 packagist 作為包的資源庫。通過指定資源庫，你可以從其他地方獲取資源包。

Repositories 并不是遞歸調用的，只能在“Root包”的 composer.json 中定義。附屬包中的 composer.json 將被忽略。

支持以下類型的包資源庫：

composer: 一個 composer 類型的資源庫，是一個簡單的網絡服務器（HTTP、FTP、SSH）上的 packages.json 文件，它包含一個 composer.json 對象的列表，有額外的 dist 和/或 source 信息。這個 packages.json 文件是用一個 PHP 流加載的。你可以使用 options 參數來設定額外的流信息。
vcs: 從 git、svn 和 hg 取得資源。
pear: 從 pear 獲取資源。
package: 如果你依賴于一個項目，它不提供任何對 composer 的支持，你就可以使用這種類型。你基本上就只需要內聯一個 composer.json 對象。

更多相關內容，請查看資源庫。

實例：

{
    "repositories": [
        {
            "type": "composer",
            "url": "http://packages.example.com"
        },
        {
            "type": "composer",
            "url": "https://packages.example.com",
            "options": {
                "ssl": {
                    "verify_peer": "true"
                }
            }
        },
        {
            "type": "vcs",
            "url": "https://github.com/Seldaek/monolog"
        },
        {
            "type": "pear",
            "url": "http://pear2.php.net"
        },
        {
            "type": "package",
            "package": {
                "name": "smarty/smarty",
                "version": "3.1.7",
                "dist": {
                    "url": "http://www.smarty.net/files/Smarty-3.1.7.zip",
                    "type": "zip"
                },
                "source": {
                    "url": "http://smarty-php.googlecode.com/svn/",
                    "type": "svn",
                    "reference": "tags/Smarty_3_1_7/distribution/"
                }
            }
        }
    ]
}

注意： 順序是非常重要的，當 Composer 查找資源包時，它會按照順序進行。默認情況下 Packagist 是最后加入的，因此自定義設置將可以覆蓋 Packagist 上的包。

config (root-only)

下面的這一組選項，僅用于項目。

支持以下選項：

process-timeout: 默認為 300。處理進程結束時間，例如：git 克隆的時間。Composer 將放棄超時的任務。如果你的網絡緩慢或者正在使用一個巨大的包，你可能要將這個值設置的更高一些。
use-include-path: 默認為 false。如果為 true，Composer autoloader 還將在 PHP include path 中繼續(xù)查找類文件。
preferred-install: 默認為 auto。它的值可以是 source、dist 或 auto。這個選項允許你設置 Composer 的默認安裝方法。
github-protocols: 默認為 ["git", "https", "ssh"]。從 github.com 克隆時使用的協議優(yōu)先級清單，因此默認情況下將優(yōu)先使用 git 協議進行克隆。你可以重新排列它們的次序，例如，如果你的網絡有代理服務器或 git 協議的效率很低，你就可以提升 https 協議的優(yōu)先級。
github-oauth: 一個域名和 oauth keys 的列表。例如：使用 {"github.com": "oauthtoken"} 作為此選項的值，將使用 oauthtoken 來訪問 github 上的私人倉庫，并繞過 low IP-based rate 的 API 限制。關聯知識關于如何獲取 GitHub 的 OAuth token。
vendor-dir: 默認為 vendor。通過設置你可以安裝依賴到不同的目錄。
bin-dir: 默認為 vendor/bin。如果一個項目包含二進制文件，它們將被連接到這個目錄。
cache-dir: unix 下默認為 $home/cache，Windows 下默認為 C:\Users\<user>\AppData\Local\Composer。用于存儲 composer 所有的緩存文件。相關信息請查看 COMPOSER_HOME。
cache-files-dir: 默認為 $cache-dir/files。存儲包 zip 存檔的目錄。
cache-repo-dir: 默認為 $cache-dir/repo。存儲 composer 類型的 VCS（svn、github、bitbucket） repos 目錄。
cache-vcs-dir: 默認為 $cache-dir/vcs。此目錄用于存儲 VCS 克隆的 git/hg 類型的元數據，并加快安裝速度。
cache-files-ttl: 默認為 15552000（6個月）。默認情況下 Composer 緩存的所有數據都將在閑置6個月后被刪除，這個選項允許你來調整這個時間，你可以將其設置為0以禁用緩存。
cache-files-maxsize: 默認為 300MiB。Composer 緩存的最大容量，超出后將優(yōu)先清除舊的緩存數據，直到緩存量低于這個數值。
prepend-autoloader: 默認為 true。如果設置為 false，composer autoloader 將不會附加到現有的自動加載機制中。這有時候用來解決與其它自動加載機制產生的沖突。
autoloader-suffix: 默認為 null。Composer autoloader 的后綴，當設置為空時將會產生一個隨機的字符串。
optimize-autoloader Defaults to false. Always optimize when dumping the autoloader.
github-domains: 默認為 ["github.com"]。一個 github mode 下的域名列表。這是用于GitHub的企業(yè)設置。
notify-on-install: 默認為 true。Composer 允許資源倉庫定義一個用于通知的 URL，以便有人從其上安裝資源包時能夠得到一個反饋通知。此選項允許你禁用該行為。
discard-changes: 默認為 false，它的值可以是 true、false 或 stash。這個選項允許你設置在非交互模式下，當處理失敗的更新時采用的處理方式。true 表示永遠放棄更改。"stash" 表示繼續(xù)嘗試。Use this for CI servers or deploy scripts if you tend to have modified vendors.

實例：

{
    "config": {
        "bin-dir": "bin"
    }
}

scripts (root-only)

Composer 允許你在安裝過程中的各個階段掛接腳本。

更多細節(jié)和案例請查看腳本。

extra

任意的，供 scripts 使用的額外數據。.

這可以是幾乎任何東西。若要從腳本事件訪問處理程序，你可以這樣做：

$extra = $event->getComposer()->getPackage()->getExtra();

可選。

bin

該屬性用于標注一組應被視為二進制腳本的文件，他們會被軟鏈接到（config 對象中的）bin-dir 屬性所標注的目錄，以供其他依賴包調用。

詳細請查看 Vendor Binaries。

可選。