• 基本用法
  • 简介
  • composer.json：项目设置
    • require 键
    • 包名
    • 包版本约束
  • 安装依赖
    • 安装时 composer.lock 文件不存在
    • 通过 composer.lock 文件安装
    • 将 composer.lock 文件提交给版本控制
  • 更新依赖项到对应的最新版本
  • Packagist
  • 平台软件包
  • 自动加载

基本用法

简介

为了我们的基本用法介绍，我们将会安装 monolog/monolog，一个日志库。 如果您还没有安装 Composer，请参考 简介 章节。

注意： 为了简单起见，本介绍将假设您已经完成了一个 Composer 的 局部安装。

composer.json：项目设置

在您的项目中开始使用 Composer，您所需要的只是一个 composer.json 文件。 这个文件描述了项目的依赖关系，并且可能包含其他元数据。

require 键

require 是第一个（通常也是唯一一个）您需要在 composer.json 中指定的东西。 您只需要简单地告诉 Composer 您的项目所依赖的包。

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

正如您所看到的，require 需要一个映射 包名（例如 monolog/monolog）到 版本限制 的对象（例如1.0.*）。

Composer 使用这些信息在包的 “资源仓库”（使用 repositories 键注册的信息中，或在默认的资源仓库 Packagist 中）搜索正确的文件。在上面的示例中，因为没有其他资源仓库在 composer.json 文件中被注册，那么我们假设 monolog/monolog 包是在 Packagist 上注册的。（请参阅章末关于 packagist 的介绍，或在 资源仓库 一章中了解更多的信息）。

包名

包名由所有者的名称与项目的名称构成。通常它们都是相同的 —— 所有者名称的存在，只是为了防止命名冲突。例如，它允许两个不同的人创建一个名为 json 的库。一个可能命名为 igorw/json，另一个可能是 seldaek/json。

请在下一章“库”中阅读更多关于发布包和包命名的内容。 （注意：您还可以指定“平台包”作为依赖项，允许您依赖特定版本的服务器软件。请查看章末关于 平台包 的介绍）

包版本约束

在我们的示例中，我们要求使用版本限制为 1.0.* 的 Monolog 包。 这意味着在 1.0 开发分支中的任何版本，或任何大于等于 1.0 并且小于 1.1（>=1.0 <1.1）的版本。

请阅读有关 版本 的更深入的信息，了解不同版本之间的关系，以及版本约束。

Composer 如何下载正确的文件？ 当您在 composer.json 中指定一个依赖项时， 首先 Composer 获取您所需要的依赖包名称，并从您在 repositories 键中注册的所有资源仓库中搜索它。 如果您没有额外注册任何资源仓库，或者它没有在您指定的资源仓库中找到对应的包名，那么就又回到了 Packagist 的问题上（更多信息请查看下文关于 Packagist 平台 的介绍）。

当 Composer 在 Packagist 或您指定的资源仓库中找到了名称正确的依赖包， 它将使用依赖包的 VCS 版本控制特性（例如，分支和标签）来尝试找到与您指定的版本约束最接近的匹配项。请务必阅读 版本与约束 一文中有关版本和包解析的内容。

注意： 如果您尝试使用 require 命令引入一个依赖包，但 Composer 抛出了一个关于包稳定性的错误，这说明您所指定的版本可能无法满足默认的最低稳定性要求。 默认情况下，在 VCS 中搜索有效的包版本时只有稳定的版本才会被考虑。

如果您试图引入一个包的 dev、alpha、beta 或 RC 版本，您可能会遇到这种情况。 请阅读 composer.json 文件结构 一章中关于稳定性标志以及 最低稳定性 的相关内容。

安装依赖

要为您的项目安装已定义的依赖，只需要运行 install 命令。

php composer.phar install

当您运行此命令时，有两件事情可能会发生：

安装时 composer.lock 文件不存在

如果您在此之前并没有运行过 install 命令，并且也不存在 composer.lock 文件， Composer 将简单的解析您在 composer.json 文件中列出的依赖项，并将其最新版本的文件下载到您项目的 vendor 目录。 （vendor 目录是一个项目中存放所有第三方代码的常规位置）。在我们的例子中，您最终会在 vendor/monolog/monolog/ 目录中得到 Monolog 的源文件。 如果 Monolog 列出了其它依赖，它们也将出现在 vendor/ 目录下。

提示： 如果您正在为您的项目使用 git，您或许会想要将 vendor 目录添加到 .gitignore 文件中。 而不是将所有的第三方代码添加到您的版本存储库中。

当 Composer 完成安装时，它将所有下载的包的确切版本写入 composer.lock 文件，将项目锁定到那些特定的版本。 您应该将 composer.lock 文件提交到您的项目仓库中。如此，所有在该项目上工作的人都会被锁定在相同的依赖。（下面会进行详细的介绍）

通过 composer.lock 文件安装

这就引出了第二个场景。如果当您运行 composer install 命令时已经存在一个与 composer.json 相似的 composer.lock 文件， 这意味着要么您在之前已经运行过 install 命令，要么当前项目的其他开发者运行了 install 命令，并提交了 composer.lock 文件。（这么做是正确的）

无论哪种方式，运行 install 命令时 composer.lock 文件是解析并安装 composer.json 中列出的所有依赖项， 而 Composer 使用 composer.lock 中列出的确切版本来确保程序包版本与工作中的每个人保持一致。 因此，您将拥有 composer.json 文件中引入的所有依赖关系 ，但它们可能并不都是最新的可用版本（自 composer.lock 文件创建以来，其中列出的某些依赖项可能已经发布了更新的版本）。 这是有意为之的，它确保您的项目不会因为依赖关系中的意外更改而中断。

将 composer.lock 文件提交给版本控制

将此文件提交到版本控制系统非常重要，因为它会使得建立项目的任何人使用您正在使用的完全相同版本的依赖。 您的持续集成服务器，生产环境设备，团队中的其他开发人员，所有人以及每个人都运行在相同的依赖关系上， 这就减少了只影响部署部分的 bug 发生的可能性。即使您独自开发，在重新安装项目的 6 个月内，您的依赖项发布了许多新版本，您也可以确信安装的依赖仍然有效。 （请参阅下面关于使用 update 命令的注意事项。）

更新依赖项到对应的最新版本

如上所述，composer.lock 文件将阻止您自动获取最新版本的依赖关系。 要更新到最新版本，请使用 update 命令。这将获取最新的匹配版本（根据您的 composer.json 文件）并使用新版本更新锁定文件。 （这相当于删除 composer.lock 文件并再次运行 install 命令。）

php composer.phar update

注意： 当执行 install 命令时如果 composer.lock 和 composer.json 未同步，Composer 将在执行命令时显示警告。

如果您只想安装或更新一个依赖项，可以将它们列入白名单（在 update 命令参数中申明）：

php composer.phar update monolog/monolog [...]

注意： 对于库，不需要提交锁定文件，另请参阅： 库 - 锁定文件。

Packagist

Packagist 是主要的 Composer 存储库。 一个 Composer 存储库基本上是一个依赖包的来源数据：您可以从中获取依赖包的位置。 Packagist 的目标是成为每个人都使用的中央存储库。这意味着您可以 require 在此处找到的任何可用的包，它自动处理，而无需您进一步指定 Composer 应在何处查找包。

如果您去 Packagist 的网站 (packagist.org)，您可以浏览和搜索依赖包。

任何使用 Composer 的开源项目都推荐在 Packagist 上发布他们的软件包。 一个库并不一定要在 Packagist 上发布，但这么做可以让其他开发人员更快地发现和采用它。

平台软件包

Composer 可以指定平台软件包，这些软件包是安装在系统上但不能由 Composer 实际安装的虚拟软件包。这包括 PHP 本身，PHP 扩展和一些系统库。

• php 代表用户的 PHP 版本，允许您应用约束，例如 >=5.4.0。如果需要 64 位版本的 php，您可以指定 php-64bit。

• hhvm 表示 HHVM 运行时的版本，并允许您应用约束，例如 >=2.3.3。

• ext-<name> 允许您指定 PHP 扩展（包括核心扩展）。版本控制在这里可能非常不一致，因此将约束设置为 * 是一个好主意。一个扩展包名称的例子是 ext-gd。

• lib-<name> 允许在 PHP 使用的库的版本上进行约束。以下是可选项：curl，iconv，icu，libxml，openssl，pcre，uuid，xsl。

您可以使用 show --platform 来获取本地可用平台包的列表。

自动加载

对于指定自动加载信息的库，Composer 会生成一个 vendor/autoload.php 文件。 您可以简单地包含此文件，并开始使用这些库提供的类，而无需额外的工作：

require __DIR__ . '/vendor/autoload.php';
$log = new Monolog\Logger('name');
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
$log->addWarning('Foo');

您甚至可以通过在 composer.json 中添加 autoload 字段将自己的代码添加到自动加载器。

{
    "autoload": {
        "psr-4": {"Acme\\": "src/"}
    }
}

Composer 将为 Acme 命名空间注册一个 PSR-4 自动加载器。

您可以定义从命名空间到目录的映射。src 目录将位于您的项目根目录中，与 vendor 目录位于同一级别。 继续上面的例子，若存在 src/Foo.php 文件，则其中应包含一个 Acme\Foo 类。

添加 autoload 字段后，您必须重新运行 dump-autoload 以重新生成 vendor/autoload.php 文件。

引入该文件还将返回自动加载器实例，因此您可以将 require 调用的返回值存储在变量中并添加更多命名空间。这对于自动加载测试套件中的类很有用。例如：

$loader = require __DIR__ . '/vendor/autoload.php';
$loader->addPsr4('Acme\\Test\\', __DIR__);

除 PSR-4 自动加载外，Composer 还支持 PSR-0，classmap 和 files 形式的自动加载。请参阅 autoload 章节以获得更多信息。

另请参阅关于 优化自动加载器 的文档。

注意： Composer 提供自己的自动加载器。 如果您不想使用，您可以引入 vendor/composer/autoload_*.php 文件， 它将返回对应的关联数组，允许您配置自己的自动加载器。

← 简介 | 库 →