• 介绍
• composer.json：项目设置
  • require 键
  • 包名
  • 包版本约束
• 安装依赖项
  • 将 composer.lock 文件提交到版本控制
  • 从 composer.lock 安装
• 将依赖项更新到最新版本
• Packagist
• 平台包
• 自动加载

基本用法#

介绍#

在我们基本用法介绍中，我们将安装 monolog/monolog，一个日志库。如果您还没有安装 Composer，请参考 入门 章节。

注意：为了简化，本介绍将假设您已执行了 Composer 的 本地 安装。

composer.json：项目设置#

要在您的项目中开始使用 Composer，您只需要一个 composer.json 文件。此文件描述了您的项目依赖项，并且可能包含其他元数据。它通常应该放在项目的顶层目录/VCS 存储库中。您可以在任何地方运行 Composer，但如果您想将包发布到 Packagist.org，它必须能够在 VCS 存储库的顶部找到该文件。

require 键#

您在 composer.json 中首先指定的是 require 键。您正在告诉 Composer 您的项目依赖哪些包。

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

如您所见，require 接受一个对象，该对象将包名（例如 monolog/monolog）映射到版本约束（例如 1.0.*）。

Composer 使用此信息在您使用 repositories 键注册的包“存储库”中搜索正确的一组文件，或在 Packagist.org（默认包存储库）中搜索。在上面的示例中，由于在 composer.json 文件中没有注册其他存储库，因此假定 monolog/monolog 包已在 Packagist.org 上注册。（阅读更多有关 Packagist 的信息，以及有关 存储库 的信息）。

包名#

包名由供应商名称和项目的名称组成。通常它们会相同 - 供应商名称只存在是为了防止命名冲突。例如，它允许两个人创建名为 json 的库。一个可能被命名为 igorw/json，而另一个可能被命名为 seldaek/json。

阅读有关 发布包和包命名 的更多信息。（请注意，您还可以指定“平台包”作为依赖项，允许您要求服务器软件的特定版本。请参阅下面的 平台包）。

包版本约束#

在我们的示例中，我们请求使用版本约束 2.0.* 的 Monolog 包。这意味着 2.0 开发分支中的任何版本，或任何大于或等于 2.0 且小于 2.1（>=2.0 <2.1）的版本。

请阅读 版本，以更深入地了解版本、版本之间的关系以及版本约束。

Composer 如何下载正确文件？当您在 composer.json 中指定依赖项时，Composer 首先获取您请求的包的名称，并在您使用 repositories 键注册的任何存储库中搜索该包。如果您没有注册任何额外的存储库，或者它在您指定的存储库中没有找到具有该名称的包，它会回退到 Packagist.org（更多信息见下文 下文）。

当 Composer 在 Packagist.org 或您指定的存储库中找到正确的包时，它会使用包的 VCS（即分支和标签）的版本控制功能来尝试找到最适合您指定的版本约束的匹配项。务必阅读有关版本和包解析的 版本文章。

注意：如果您尝试要求一个包，但 Composer 抛出有关包稳定性的错误，您指定的版本可能不符合您的默认最低稳定性要求。默认情况下，在 VCS 中搜索有效包版本时，只会考虑稳定版本。

如果您尝试要求包的开发版、alpha 版、beta 版或 RC 版，您可能会遇到这种情况。在 架构页面 上阅读有关稳定性标志和 minimum-stability 键的更多信息。

安装依赖项#

要最初安装为您的项目定义的依赖项，您应该运行 update 命令。

php composer.phar update

这将使 Composer 做两件事

• 它解析 composer.json 文件中列出的所有依赖项，并将所有包及其确切版本写入 composer.lock 文件，将项目锁定到这些特定版本。您应该将 composer.lock 文件提交到您的项目存储库中，以便所有参与项目的人员都锁定在相同的依赖项版本上（更多信息见下文）。这是 update 命令的主要作用。
• 然后它隐式运行 install 命令。这会将依赖项的文件下载到您项目中的 vendor 目录。（vendor 目录是项目中所有第三方代码的传统位置）。在上面的示例中，您最终会在 vendor/monolog/monolog/ 中找到 Monolog 源文件。由于 Monolog 依赖于 psr/log，因此该包的文件也可以在 vendor/ 中找到。

提示：如果您在项目中使用 git，您可能希望在 .gitignore 中添加 vendor。您真的不想将所有这些第三方代码添加到您的版本控制存储库中。

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

将此文件提交到版本控制很重要，因为它会让任何设置项目的人使用与您使用的相同的依赖项版本。您的 CI 服务器、生产机器、团队中的其他开发人员，所有东西和所有人都使用相同的依赖项，这减轻了仅影响部署某些部分的潜在错误。即使您独自开发，在六个月后重新安装项目时，您也可以确信已安装的依赖项仍然有效，即使自那时起依赖项已发布了许多新版本。（请参阅下面关于使用 update 命令的说明）。

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

从 composer.lock 安装#

如果项目文件夹中已经存在 composer.lock 文件，则意味着您之前运行过 update 命令，或者项目中的其他人运行过 update 命令并将 composer.lock 文件提交到项目中（这很好）。

无论哪种方式，当存在 composer.lock 文件时运行 install 将解析并安装 composer.json 中列出的所有依赖项，但 Composer 使用 composer.lock 中列出的确切版本来确保包版本对所有参与项目的人员都是一致的。因此，您将拥有 composer.json 文件请求的所有依赖项，但它们可能并不都在最新的可用版本中（composer.lock 文件中列出的某些依赖项自文件创建以来可能已发布了更新版本）。这是有意为之，以确保您的项目不会因为依赖项中的意外更改而中断。

因此，在从 VCS 存储库中获取新的更改后，建议运行 Composer install 以确保 vendor 目录与 composer.lock 文件同步。

php composer.phar install

Composer 默认情况下启用可重现构建。这意味着多次运行相同的命令将生成包含完全相同文件（除了其时间戳）的 vendor/ 目录，包括自动加载文件。这对于需要严格验证流程的环境以及旨在以安全且可预测的方式打包 PHP 应用程序的 Linux 发行版特别有用。

将依赖项更新到最新版本#

如上所述，composer.lock 文件阻止您自动获取依赖项的最新版本。要更新到最新版本，请使用 update 命令。这将获取最新的匹配版本（根据您的 composer.json 文件）并使用新版本更新锁定文件。

php composer.phar update

注意：如果自对 composer.json 进行可能影响依赖项解析的更改以来尚未更新 composer.lock，Composer 在执行 install 命令时将显示警告。

如果您只想安装、升级或删除一个依赖项，可以将其明确列为参数

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

Packagist#

Packagist.org 是主要的 Composer 存储库。Composer 存储库基本上是包源：您可以从中获取包的地方。Packagist 旨在成为每个人都使用的中心存储库。这意味着您可以自动 require 那里可用的任何包，而无需进一步指定 Composer 应该在哪里查找包。

如果您访问 Packagist.org 网站，您可以浏览和搜索包。

建议任何使用 Composer 的开源项目将他们的包发布到 Packagist 上。库不需要在 Packagist 上才能被 Composer 使用，但它可以让其他开发人员更快地发现和采用它。

平台包#

Composer 有平台包，它们是针对系统上安装但实际上无法由 Composer 安装的事物的虚拟包。这包括 PHP 本身、PHP 扩展和一些系统库。

• php 代表用户的 PHP 版本，允许您应用约束，例如 ^7.1。要要求 64 位版本的 php，您可以要求 php-64bit 包。

• hhvm 代表 HHVM 运行时的版本，允许您应用约束，例如 ^2.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->warning('Foo');

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

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

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

您定义了从命名空间到目录的映射。src 目录将位于您的项目根目录中，与 vendor 目录处于同一级别。一个示例文件名是 src/Foo.php，其中包含一个 Acme\Foo 类。

在添加 autoload 字段后，您必须重新运行此命令。

php composer.phar dump-autoload

此命令将重新生成 vendor/autoload.php 文件。有关更多信息，请参见 dump-autoload 部分。

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

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

除了 PSR-4 自动加载，Composer 还支持 PSR-0、类映射和文件自动加载。有关更多信息，请参见 autoload 参考资料。

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

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

← 简介 | 库 →

发现错别字了吗？文档中有什么问题吗？ 分叉并编辑 它！