composer.json 架构

composer.json 架构

本章将解释所有在 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 这些后缀是可选的。在后缀之后也可以再跟上一个数字。

例：

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 创建一个新的工作区时，这可以为其提供项目列表的初始化。
metapackage: 当一个空的包，包含依赖并且需要触发依赖的安装，这将不会对系统写入额外的文件。因此这种安装类型并不需要一个 dist 或 source。
composer-plugin: 一个安装类型为 composer-plugin 的包，它有一个自定义安装类型，可以为其它包提供一个 installler。详细请查看自定义安装类型。

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

关键字 `keywords`

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

实例：

logging
events
database
redis
templating

可选。

项目主页 `homepage`

该项目网站的 URL 地址。

可选。

版本发布时间 `time`

版本发布时间。

必须符合 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: 该作者在此项目中担任的角色（例：开发人员或翻译）。

一个实例：

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

实例：

{
    "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"
    }
}

注意： 虽然这有时很方便，但不应该长期在你的包中使用，因为它有一个技术上的限制。
composer.json 将仍然在哈希值之前指定的分支名称读取元数据，
正因为如此，在某些情况下，它不会是一个实用的解决方法，
如果可能，你应该总是尝试切换到拥有标签的版本。

它也可以应用于行内别名，这样它将匹配一个约束，否则不会。更多信息请参考别名。

require

必须的软件包列表，除非这些依赖被满足，否则不会完成安装。

require-dev (root-only)

这个列表是为开发或测试等目的，额外列出的依赖。“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 一个包，以不同的名称和版本号发布，同时要求依赖于原包的其它包，在这之后依赖于你 fork 的这个包，因为它取代了原来的包。

这对于创建一个内部包含子包的主包也非常的有用。例如 symfony/symfony 这个主包，包含了所有 Symfony 的组件，而这些组件又可以作为单独的包进行发布。如果你 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\\ 将会被区分开来。

在 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 规范的类库。要配置它指向需要的目录，以便能够准确搜索到类文件。

实例：

{
    "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)

这定义了通过稳定性过滤包的默认行为。默认为 stable（稳定）。因此如果你依赖于一个 dev（开发）包，你应该明确的进行定义。

对每个包的所有版本都会进行稳定性检查，而低于 minimum-stability 所设定的最低稳定性的版本，将在解决依赖关系时被忽略。对于个别包的特殊稳定性要求，可以在 require 或 require-dev 中设定（请参考 Package links）。

可用的稳定性标识（按字母排序）：dev、alpha、beta、RC、stable。

prefer-stable (root-only)

当此选项被激活时，Composer 将优先使用更稳定的包版本。

使用 "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 中继续查找类文件。
preferred-install: 默认为 auto。它的值可以是 source、dist 或 auto。这个选项允许你设置 Composer 的默认安装方法。
github-protocols: 默认为 ["git", "https", "ssh"]。从 github.com 克隆时使用的协议优先级清单，因此默认情况下将优先使用 git 协议进行克隆。你可以重新排列它们的次序，例如，如果你的网络有代理服务器或 git 协议的效率很低，你就可以提升 https 协议的优先级。
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 缓存的最大容量，超出后将优先清除旧的缓存数据，直到缓存量低于这个数值。
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的企业设置。
notify-on-install: 默认为 true。Composer 允许资源仓库定义一个用于通知的 URL，以便有人从其上安装资源包时能够得到一个反馈通知。此选项允许你禁用该行为。
discard-changes: 默认为 false，它的值可以是 true、false 或 stash。这个选项允许你设置在非交互模式下，当处理失败的更新时采用的处理方式。true 表示永远放弃更改。"stash" 表示继续尝试。Use this for CI servers or deploy scripts if you tend to have modified vendors.

实例：

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

scripts (root-only)

Composer 允许你在安装过程中的各个阶段挂接脚本。

更多细节和案例请查看脚本。

extra

任意的，供 scripts 使用的额外数据。.

这可以是几乎任何东西。若要从脚本事件访问处理程序，你可以这样做：

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

可选。

bin

该属性用于标注一组应被视为二进制脚本的文件，他们会被软链接到（config 对象中的）bin-dir 属性所标注的目录，以供其他依赖包调用。

详细请查看 Vendor Binaries。

可选。

架构