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 文件，但上下文发生了变化。

注意： 一个资源包是不是“root 包”，取决于它的上下文。 例：如果你的项目依赖 monolog 库，那么你的项目就是“root 包”。 但是，如果你从 GitHub 上克隆了 monolog 为它修复 bug， 那么此时 monolog 就是“root 包”。

属性 包名 name

包的名称，它包括供应商名称和项目名称，使用 / 分隔。

例：

monolog/monolog

igorw/event-source

对于需要发布的包（库），这是必须填写的。

描述 description

一个包的简短描述。通常这个最长只有一行。

对于需要发布的包（库），这是必须填写的。

版本 version

version 不是必须的，并且建议忽略（见下文）。

它应该符合 'X.Y.Z' 或者 'vX.Y.Z' 的形式， -dev、-patch、-alpha、-beta 或 -RC 这些后缀是可选的。在后缀之后也可以再跟上一个数字。

例：

通常，我们能够从 VCS (git, svn, hg) 的信息推断出包的版本号，在这种情况下，我们建议忽略 version。

注意： Packagist 使用 VCS 仓库， 因此 version 定义的版本号必须是真实准确的。 自己手动指定的 version，最终有可能在某个时候因为人为错误造成问题。

安装类型 type

包的安装类型，默认为 library。

包的安装类型，用来定义安装逻辑。如果你有一个包需要一个特殊的逻辑，你可以设定一个自定义的类型。这可以是一个 symfony-bundle，一个 wordpress-plugin 或者一个 typo3-module。这些类型都将是具体到某一个项目，而对应的项目将要提供一种能够安装该类型包的安装程序。

composer 原生支持以下4种类型：

仅在你需要一个自定义的安装逻辑时才使用它。建议忽略这个属性，采用默认的 library。

关键字 keywords

该包相关的关键词的数组。这些可用于搜索和过滤。

实例：

可选。

项目主页 homepage

该项目网站的 URL 地址。

可选。

版本发布时间 time

版本发布时间。

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

可选。

许可协议 license

包的许可协议，它可以是一个字符串或者字符串数组。

最常见的许可协议的推荐写法（按字母排序）：

可选，但强烈建议提供此内容。更多许可协议的标识符请参见 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

包的作者。这是一个对象数组。

这个对象必须包含以下属性：

一个实例：

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

可选，但强烈建议提供此内容。

支持 support

获取项目支持的向相关信息对象。

这个对象必须包含以下属性：

一个实例：

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

可选。

Package links

下面提到的所有对象，都应该是 包名 到 的映射对象。

实例：

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

所有的这些都是可选的。

require 和 require-dev 还支持稳定性标签（@，仅针对“root 包”）。这允许你在 设定的范围外做进一步的限制或扩展。例：如果你想允许依赖一个不稳定的包，你可以在一个包的版本约束后使用它，或者是一个空的版本约束内使用它。

实例：

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

如果你的依赖之一，有对另一个不稳定包的依赖，你最好在 require 中显示的定义它，并带上足够详细的稳定性标识。

实例：

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

require 和 require-dev 还支持对 dev（开发）版本的明确引用（即：版本控制系统中的提交编号 commit），以确保它们被锁定到一个给定的状态，即使你运行了更新命令。你只需要明确一个开发版本号，并带上诸如 #<ref> 的标识。

实例：

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