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),以确保它们被锁定到一个给定的状态,即使你运行了更新命令。你只需要明确一个开发版本号,并带上诸如 # 的标识。

例:

{
    "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 的自动加载映射。

通常 PSR-0 autoloading、classmap generation 和 files 方式都是支持的。PSR-0 是推荐的方式,因为它提供了更大的灵活性(当你添加新的类文件时,不需要重新生成 autoloader)。

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

例:

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

Files

如果你想要明确的指定,在每次请求时都要载入某些文件,那么你可以使用 ‘files’ autoloading。通常作为函数库的载入方式(而非类库)。

例:

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

include-path

不建议:这是目前唯一支持传统项目的做法,所有新的代码都建议使用自动加载。 这是一个过时的做法,但 Composer 将仍然保留这个功能。

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

例:

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

可选。

target-dir

定义当前包安装的目标文件夹。

若某个包的根目录,在它申明的命名空间之下,将不能正确的使用自动加载。而 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"]。从 github.com 克隆时使用的协议优先级清单,因此默认情况下将优先使用 git 协议进行克隆。
github-oauth: 一个域名和 oauth keys 的列表。例如:使用 {"github.com": "oauthtoken"} 作为此选项的值,将使用 oauthtoken 来访问 github 上的私人仓库,并绕过 low IP-based rate 的 API 限制。
vendor-dir: 默认为 vendor。通过设置你可以安装依赖到不同的目录。
bin-dir: 默认为 vendor/bin。如果一个项目包含二进制文件,它们将被连接到这个目录。
cache-dir: unix 下默认为 $home/cache,Windows 下默认为 C:\Users\&lt;user&gt;\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 的后缀,当设置为空时将会产生一个随机的字符串。
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-&gt;getComposer()-&gt;getPackage()-&gt;getExtra();

可选。

bin

A set of files that should be treated as binaries and symlinked into the bin-dir (from config).

See Vendor Binaries for more details.

可选。

archive

这些选项在创建包存档时使用。

支持以下选项:

exclude: 允许设置一个需要被排除的路径的列表。使用与 .gitignore 文件相同的语法。一个前导的(!)将会使其变成白名单而无视之前相同目录的排除设定。前导斜杠只会在项目的相对路径的开头匹配。星号为通配符。

例:

{
    "archive": {
        "exclude": ["/foo/bar", "baz", "/*.test", "!/foo/bar/baz"]
    }
}

在这个例子中我们 include /dir/foo/bar/file、/foo/bar/baz、/file.php、/foo/my.test 但排除了 /foo/bar/any、/foo/baz、/my.test。

可选。

发表评论

电子邮件地址不会被公开。 必填项已用*标注

This site uses Akismet to reduce spam. Learn how your comment data is processed.