库（资源包）

本章将告诉你如何通过 Composer 来安装你的库。

每一个项目都是一个包

只要你有一个 composer.json 文件在目录中，那么整个目录就是一个包。当你添加一个 require 到项目中，你就是在创建一个依赖于其它库的包。你的项目和库之间唯一的区别是，你的项目是一个没有名字的包。

为了使它成为一个可安装的包，你需要给它一个名称。你可以通过 composer.json 中的 name 来定义：

  1. {
  2.     "name": "acme/hello-world",
  3.     "require": {
  4.         "monolog/monolog": "1.0.*"
  5.     }
  6. }

在这种情况下项目的名称为 acme/hello-world，其中 acme 是供应商的名称。供应商的名称是必须填写的。

注意： 如果你不知道拿什么作为供应商的名称， 那么使用你 github 上的用户名通常是不错的选择。 虽然包名不区分大小写，但惯例是使用小写字母，并用连字符作为单词的分隔。

平台软件包

Composer 将那些已经安装在系统上，但并不是由 Composer 安装的包视为一个虚拟的平台软件包。这包括PHP本身，PHP扩展和一些系统库。

  • php 表示用户的 PHP 版本要求，你可以对其做出限制。例如 >=5.4.0。如果需要64位版本的 PHP，你可以使用 php-64bit 进行限制。

  • hhvm 代表的是 HHVM（也就是 HipHop Virtual Machine） 运行环境的版本，并且允许你设置一个版本限制，例如，'>=2.3.3'。

  • ext- 可以帮你指定需要的 PHP 扩展（包括核心扩展）。通常 PHP 拓展的版本可以是不一致的，将它们的版本约束为 * 是一个不错的主意。一个 PHP 扩展包的例子：包名可以写成 ext-gd。

  • lib- 允许对 PHP 库的版本进行限制。

以下是可供使用的名称：curl、iconv、icu、libxml、openssl、pcre、uuid、xsl。

你可以使用 composer show --platform 命令来获取可用的平台软件包的列表。

指明版本

你需要一些方法来指明自己开发的包的版本，当你在 Packagist 上发布自己的包，它能够从 VCS (git, svn, hg) 的信息推断出包的版本，因此你不必手动指明版本号，并且也不建议这样做。请查看 标签 和 分支 来了解版本号是如何被提取的。

如果你想要手动创建并且真的要明确指定它，你只需要添加一个 version 字段：

  1. {
  2.     "version": "1.0.0"
  3. }

注意： 你应该尽量避免手动设置版本号，因为标签的值必须与标签名相匹配。

标签

对于每一个看起来像版本号的标签，都会相应的创建一个包的版本。它应该符合 'X.Y.Z' 或者 'vX.Y.Z' 的形式，-patch、-alpha、-beta 或 -RC 这些后缀是可选的。在后缀之后也可以再跟上一个数字。

下面是有效的标签名称的几个例子：

  • 1.0.0
  • v1.0.0
  • 1.10.5-RC1
  • v4.4.4beta2
  • v2.0.0-alpha
  • v2.0.4-p1

注意： 即使你的标签带有前缀 v， 由于在需要 require 一个版本的约束时是不允许这种前缀的， 因此 v 将被省略（例如标签 V1.0.0 将创建 1.0.0 版本）。

分支

对于每一个分支，都会相应的创建一个包的开发版本。如果分支名看起来像一个版本号，那么将创建一个如同 {分支名}-dev 的包版本号。例如一个分支 2.0 将产生一个 2.0.x-dev 包版本（加入了 .x 是出于技术的原因，以确保它被识别为一个分支，而 2.0.x 的分支名称也是允许的，它同样会被转换为 2.0.x-dev）。如果分支名看起来不像一个版本号，它将会创建 dev-{分支名} 形式的版本号。例如 master 将产生一个 dev-master 的版本号。

下面是版本分支名称的一些示例：

  • 1.x
  • 1.0 (equals 1.0.x)
  • 1.1.x

注意： 当你安装一个新的版本时，将会自动从它 source 中拉取。 详细请查看 install 命令。

别名

它表示一个包版本的别名。例如，你可以为 dev-master 设置别名 1.0.x-dev，这样就可以通过 require 1.0.x-dev 来得到 dev-master 版本的包。

详细请查看“别名”。

锁文件

如果你愿意，可以在你的项目中提交 composer.lock 文件。他将帮助你的团队始终针对同一个依赖版本进行测试。任何时候，这个锁文件都只对于你的项目产生影响。

如果你不想提交锁文件，并且你正在使用 Git，那么请将它添加到 .gitignore 文件中。

发布到 VCS（线上版本控制系统）

一旦你有一个包含 composer.json 文件的库存储在线上版本控制系统（例如：Git），你的库就可以被 Composer 所安装。在这个例子中，我们将 acme/hello-world 库发布在 GitHub 上的 github.com/username/hello-world 中。

现在测试这个 acme/hello-world 包，我们在本地创建一个新的项目。我们将它命名为 acme/blog。此博客将依赖 acme/hello-world，而后者又依赖 monolog/monolog。我们可以在某处创建一个新的 blog 文件夹来完成它，并且需要包含 composer.json 文件：

  1. {
  2.     "name": "acme/blog",
  3.     "require": {
  4.         "acme/hello-world": "dev-master"
  5.     }
  6. }

在这个例子中 name 不是必须的，因为我们并不想将它发布为一个库。在这里为 composer.json 文件添加描述。

现在我们需要告诉我们的应用，在哪里可以找到 hello-world 的依赖。为此我们需要在 composer.json 中添加 repositories 来源申明：

  1. {
  2.     "name": "acme/blog",
  3.     "repositories": [
  4.         {
  5.             "type": "vcs",
  6.             "url": "https://github.com/username/hello-world"
  7.         }
  8.     ],
  9.     "require": {
  10.         "acme/hello-world": "dev-master"
  11.     }
  12. }

更多关于包的来源是如何工作的，以及还有什么其他的类型可供选择，请查看资源库。

这就是全部了。你现在可以使用 Composer 的 install 命令来安装你的依赖包了！

小结： 任何含有 composer.json 的 GIT、SVN、HG 存储库，都可以通过 require 字段指定“包来源”和“声明依赖”来添加到你的项目中。

发布到 packagist

好的，你现在可以发布你的包了，但你不会希望你的用户每次都这样繁琐的指定包的来源。

你可能注意到了另一件事，我们并没有指定 monolog/monolog 的来源。它是怎么工作的？答案是 packagist。

Packagist 是 Composer 主要的一个包信息存储库，它默认是启用的。任何在 packagist 上发布的包都可以直接被 Composer 使用。就像 monolog 它被 发布在 packagist 上，我们可以直接使用它，而不必指定任何额外的来源信息。

如果我们想与世界分享我们的 hello-world，我们最好将它发布到 packagist 上。这样做是很容易的。

你只需要点击那个大大的 "Submit Package" 按钮并注册。接着提交你库的来源地址，此时 packagist 就开始了抓取。一旦完成，你的包将可以提供给任何人使用。