Composer 之 composer.json 配置文件说明

▪ 前言

Java 有 Maven, Node.js 有 npm, ROR 有 gem, 这些语言的程序员在开心地使用包管理工具加速开发效率时，PHPer 们还在复制粘贴的黑暗中。PHP 在 Composer 之前，包管理的历史不堪回首。

在相当长的一段时间内，如果应用依赖于第三方库，PHPer 们需要拷贝这些库的源代码， 或者通过 PEAR、PECL 安装。如果第三方库又依赖于更多的第三方库，那么很快就会进入依赖的黑洞。直到 Composer 出现，PHPer 们看到了属于 PHP 的包管理的曙光。

下面将以创建一个电商网站为例，介绍 Composer 的使用方法。

一、配置文件

在我们开始一个项目的时候，首先会给项目取一个名字，我们暂且叫 电子商城，代号
eshop
。首先要写一个 Composer 的配置文件，来描述项目，为此，在项目的根目录下，建立文件名为 composer.json 的配置文件。内容如下：

{
    "name":             "dmlk31/eshop",
    "description":      "another e-commerce website",
    "keywords":         ["dmlk31", "online shop", "good", "eshop"],
    "homepage":         "http://www.xxx.com",
    "time":             "2014-12-30",
    "license":          "MIT",
    "authors": [{
        "name":         "dmlk31",
        "email":        "dmlk31@xxxx.com",
        "homepage":     "http://www.xxxx.com",
        "role":         "Engineer"
    }]
}

如果您熟悉 JSON 格式，那么上面这段内容不言而喻。事实上，这些键值对都是可选的。也就是说，可以都不写。但是如果要把项目打包成公共包发布，那么这些还是需要写上的，给你的包取个名字总不为过。让我们来过一下这些键值对的意义吧。

"name" : "dmlk31/eshop"

name 表示包的名称。如果你经常在 Github 上混，那这个值的表达方式一定非常熟悉啦。解释下，通常包名包含两部分，并且以 / 分隔。斜杆前面部分，代表包的所有者。目前大部分的包作者都喜欢用 Github 的用户名作为这部分的值。斜杆后面部分代表包的名称。尽量保持简单和有意义些，便于记忆和传播。大部分情况下，很多人会用 Github 的代码库名称来命名，当然，这种情况下，代码要存在 Github 比较有意义。

"description" : "another e-commerce website"

应用简介，这部分尽量简洁介绍下项目，别长篇大论。如果确实有很多话要说，那么可以写在 README.md 文件里。

"keywords" : ["dmlk31", "online shop", "good", "eshop"]

关键词的值是一个字符串数组，在发布成公用库的是时候，作为元数据信息，有利于包的搜索和发现。

"homepage" :  "http://www.xxx.com"

主页，可以放你想放的任何页面地址。

"license" : "MIT"

如果你决定将包公开发布，那么记得选择一个合适的许可证。这样别的程序员在引用包的时候，通过查看许可证，确保没有法律上的问题。

"authors" : [{}]

作者字段可以包含一个对象数组，也就是说可以提供多个作者信息。

目前为止，都是关于包本身的信息描述。作为一个电子商城网站，能够发送电子邮件、导出订单到 Excel 表是基本需求，这个时候自然想到了使用现有的库来实现这些功能。要获取这些库，最简单的方式是：搜索下这些库，找到下载地址，下载个zip包，然后解压到相应目录下，根据文档引入相应的文件。使用 Composer，可以更加自动和优雅地完成这个过程，这就是 Composer 的依赖管理。

二、依赖管理

在 composer.json 文件里增加一个新的字段：require。这个字段的值是一个对象，同样以键值对的形式构成。以上述提到的两个依赖位置，写成 Composer 管理的方式如下：

2.1 require

"require": {
    "phpoffice/phpexcel"      : "dev-master",
    "swiftmailer/swiftmailer" : "5.3.*@dev"
}

以 swiftmailer 为例，swiftmailer/swiftmailer 代表的是包名称，5.3.*@dev 是版本信息。合起来的意思就是说，我们将要开发的应用，依赖于 swiftmailer 的 5.3.* 版本。其中：

5.3.* 表示：可以使用 5.3.1 版本，也可以使用 5.3.2 版本，Composer 在获取的时候，将寻找 5.3 版本下最新的版本。版本号支持一些更加宽泛的约束，比如 >=1.0, >=1.0, <2.0，更加具体的信息可以查看：http://docs.phpcomposer.com/01-basic-usage.md#The-require-Key

@dev 表示可以获取开发版本。通常，开发版本意味非稳定版本，很可能存在bug。稳定性标签可以作用于特定的依赖项，也可以作用于全局。

作用特定依赖项：默认情况下，Composer 只会获取稳定版本，如果这个例子我们不加 @dev 约束，而 5.3.* 版本都是开发版本，那么在获取的时候 Composer 就会报错，指出改版本不符合要求。如果确定这个开发版本没有问题，那么就可以通过加@dev，让 Composer 获取这个开发版本。

全局稳定性设置：通过设置 minimum-stability 的值，来告诉 Composer 当前开发的项目的依赖要求的包的全局稳定性级别，它的值包括：dev、alpha、beta、RC、stable，stable 是默认值。

至此，两个依赖添加完毕，我们可以运行下 Composer 包更新命令，看看效果啦：

$ composer install

成功运行完毕，会在根目录下发现 vendor 文件夹，里面包含了刚刚我们列出来的两个包文件代码。

2.2 require-dev

有时候，我们会发现，有些包依赖只会在开发过程中使用，正式发布的程序不需要这些包，这个时候，就需要用到另外一个键，即 require-dev。例如，我们想用 codeception 进行单元测试，那么就可以通过 require-dev 引入这个开发环境下的依赖包：

"require-dev": {
    "codeception/codeception": "2.0.0"
}

加了这个依赖后，再运行下命令看看效果：

$ composer install

三、自动加载

自此，Composer 已经帮我们把需要的库文件下载下来啦，接下去想到的就是如何引用这些库文件。最简单的方式就是 require 或者 include，但这就不够高大上了啊，需要花时间去库文件里查看需要引入哪些文件，费事而且容易出错。好在 Composer 可以帮我们解决这个问题。那就是 autoload。

在运行完 composer install 命令后，怎么调用 PHPExcel 库呢？很简单，只要引入 vendor 目录下的 autoload.php 文件就可以了。可以在根目录下，建一个 index.php 文件，加入一下内容：

include 'vendor/autoload.php'
$excel = new PHPExcel();
var_dump($excel);

用浏览器访问一下这个页面，就会发现 PHPExcel 对象已经被成功创建啦，是不是很方便？

其实到目前为止，我们并没用在 composer.json 文件里加入 autoload 字段，那么什么时候需要加入呢？ 那就是当我们想让 Composer 帮我们自动加载我们自己定义的类的时候。例如，我们自己写了个订单管理类，取名 OrderManager，放在 lib 目录下的 OrderManager.php 文件里。内容如下：

class OrderManager
{
    public function test()
    {
        echo 'hello';
    }
}

那么如何让 Composer 帮我们自动加载这个类呢？ 在 composer.json 里加入下面的内容？

3.1 使用 files 方式（通常作为函数库的载入方式，而非类库）

"autoload":{
    "files" : ["lib/OrderManager.php"]
}

files 键对应的值是一个数组，数组元素是文件的路径，路径是相对于应用的根目录。加上上述内容后，运行命令：

$ composer dump-autoload

让 Composer 重建自动加载的信息，完成之后，就可以在 index.php 里调用 OrderManager 类啦。

3.2 使用 classmap 方式

通过文件引入的方法虽然直观，但是很费劲，每个文件都得引入一次，实在不是好的解决办法。有没有更好的办法呢？尝试将 autoload 的值改成：

"classmap" : ["lib"]

再此运行 composer dump-autoload，尝试调用，依然能够成功创建 OrderManager 类。

其实，classmap 通过建立类到文件的对应关系，当程序需要 OrderManager 类时，Composer 的自动加载类通过查找 OrderManager 类所在的文件，然后再将改文件 include 进来。

因此，这又导致了一个问题，那就是每加一个新类，就需要运行一次 composer dump-autoload 来创建类到文件到对应关系，比 files 方法虽然好一点，但是还是很不够舒爽啊！于是，PSR-0 出场了。先了解下什么是 PSR-0。

3.3 PSR0/4 加载方式

FIG 组织制定的一组 PHP 相关规范，简称 PSR，其中：

PSR-0 自动加载

PSR-1 基本代码规范

PSR-2 代码样式

PSR-3 日志接口

PSR-4 自动加载

目前就这五个规范，乍一看，PSR-0 和 PSR-4 是重复了，实际上，在功能上确实有所重复。区别在于 PSR-4 的规范比较干净，去除了兼容 PHP 5.3 以前版本的内容，有一点 PSR-0 升级版的感觉。当然，PSR-4 也不是要完全替代 PSR-0，而是在必要的时候补充 PSR-0。

PSR-4 规范的具体内容见：http://blog.csdn.net/hel12he/article/details/45602263

简而言之，就是希望通过一组约定的目录，文件名，类名定义方式，来实现快速通过类查找到文件，然后包含进来，实现自动加载。
PSR-4 和 PSR-0 最大的区别是对下划线（underscore）的定义不同。PSR-4 中，在类名中使用下划线没有任何特殊含义。而 PSR-0 则规定类名中的下划线_会被转化成目录分隔符。

不管是 PSR-0 还是 PSR-4，都要求有个命名空间，所以我们需要对 OrderManager 类进行一些小的修改，加上命名空间：

namespace EShopLib;
class OrderManager
{
    public function test()
    {
        echo "hello";
    }
 }

同时，文件夹的结构也要修改成：lib\EShopLib\OrderManager.php

然后修改 composer.json 里的 autoload 部分如下：

"autoload":{
   "psr-0":{
       "EShopLib" : "lib/"
   }
}

这里需要注意的是，EShopLib 是命名空间，lib 是目录名，他们的组合告诉 Composer，文件搜索是在：lib/EShopLib/ 目录下，而不是在 EShopLib/lib 目录下，这一点要特别注意，有点绕，容易弄错。

如果我们把命名空间改成 EShop\lib, 相应的目录结构要改成：lib\EShop\lib\OrderManager.php，autoload 部分的写法相应的也要改成：

"autoload":{
    "psr-0":{
        "Silk\\lib" : "lib/"
    }
}

好了，那我们试试再加一个类，然后不用运行 composer dump-autoload 命令，看看新类是否能加载上。在 lib 目录下，新增一个 ShipManager.php 文件，内容如下：

namespace EShop\lib;
class ShipManager
{
    public function test()
    {
        echo 'hello ship class';
    }
}

尝试在 index.php 文件中调用：

$orderMgr = new Silk\lib\OrderManager();
$orderMgr->test();
$shipMgr = new Silk\lib\ShipManager();
$shipMgr->test();

运行成功，说明使用 PSR-0 规范进行自动加载，比 classmap 更加方便。下面试试 PSR-4 方式，整理下目录结构，改成：lib\OrderManager.php，修改命名空间为 EShop, 修改 autoload 部分为：

"autoload":{
    "psr-4":{
        "EShop":"lib"
    }
}

尝试调用，发现报错 Fatal error: Uncaught exception ‘InvalidArgumentException’ with message ‘A non-empty PSR-4 prefix must end with a namespace separator. 提示要加上分隔符，那就加上吧：

"autoload":{
    "psr-4":{
        "Silk\\":"lib"
    }
}

再次 composer dump-autoload，运行测试，OK通过！