Basic usage(基本用法)#

Introduction(介绍)#

对于我们的基本使用介绍, 我们将安装monolog/monolog, 一个日志库。如果尚未安装Composer, 请参阅介绍章节.

注意: 为了简单起见, 本介绍将假定您已经执行了局部的Composer安装.

composer.json: Project setup( composer.json: 项目设置)#

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

The require key(require 键)#

在composer.json中指定的第一个内容是require键。告诉Composer你的项目所依赖的软件包。

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

正如您所看到的, require用一个对象, 将包名 (例如monolog/monolog) 映射到版本约束 (例如1.0.*)。

Composer 使用这些信息在您使用repositories键注册的包“仓库（repositories）”, 或者在默认的包仓库 Packagist.org中 来寻找正确的文件。 。 在上面的示例中, 由于没有在composer.json文件中注册其他仓库(repositories), 因此假定monolog/monolog包在Packagist.org 上注册。 (阅读更多关于Packagist，以及 关于存储库).

Package names(包名称)#

包名称由供应商名称和项目名称组成。通常, 这些将是相同的-供应商名称仅为了防止命名冲突。例如, 它允许两个不同的人创建一个名为json的库。一个可能被命名为 p2hp/json, 而另一个可能是 lenix/json。

阅读更多发布包和包命名。(请注意, 您还可以将 "平台包" 指定为依赖项, 从而允许您require某些版本的服务器软件。请参阅下面的平台软件包。)

Package version constraints(包版本约束)#

在我们的示例中, 我们要求具有版本约束2.0.*的Monolog包。这意味着2.0开发分支中的任何版本, 或者大于或等于2.0 且小于 2.1 (>=2.0 <2.1) 的任何版本。

请阅读版本, 了解有关版本、版本相互关联以及版本约束的更多详细信息.

Composer如何下载正确的文件？ 当你在composer.json中指定依赖项时, Composer首先获取您要求的包的名称, 并在使用repositories键注册的任何仓库中搜索它。如果您尚未注册任何额外的仓库, 或者它在您指定的仓库中找不到具有该名称的包, 则它将返回到Packagist.org 中寻找(更多 在下面)。

当Composer在 Packagist 或您指定的仓库中找到合适的包时, 它会使用包的 VCS (即分支和标记) 的版本控制功能来尝试找到您指定的版本约束的最佳匹配。请务必在版本文章中阅读有关版本和包解析的信息.

注意:如果您试图请求一个包, 但Composer抛出一个关于包稳定性的错误, 您指定的版本可能无法满足默认的最低稳定性要求。默认情况下, 在您的 VCS 中搜索有效的包版本时, 只考虑稳定的版本.

如果您试图要求dev、alpha、beta 或 RC 版本的软件包, 则可能会遇到此问题。在 结构页上阅读有关稳定性标记和最小稳定性minimum-stability键的更多信息。

Installing dependencies(安装依赖项)#

若要最初为项目安装定义的依赖项，应运行 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 命令的说明。

注: 对于库(libraries)，无需提交锁定文件，另请参阅：Libraries - Lock file.

从 composer.lock 安装#

如果项目文件夹中已经有一个 composer.lock 文件，则表示您之前运行了 update 命令，或者项目中的其他人运行了 update 命令并将 composer.lock文件提交到项目（这很好）.

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

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

php composer.phar install

Updating dependencies to their latest versions(更新依赖到它们的最新版本)#

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

php composer.phar update

注意: Composer将在执行install命令时显示警告, 如果 composer.lock 在composer.json变更后没有被更新，则可能会影响依赖解析 ..

如果只想安装，升级或移除一个依赖项, 您可以显式地将它作为参数列出:

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

Packagist#

Packagist.org是主要的Composer仓库。Composer仓库基本上是一个包源: 一个可以从中获取包的地方。Packagist 的目标是成为每个人都使用的中央仓库。这意味着您可以自动require任何可用的包, 而无需进一步指定Composer应在何处查找包.

如果你去 Packagist.org 网站, 你可以浏览和搜索包。

推荐任何开源项目 使用Composer在Packagist上发布它们的包.一个库不需要一定在Packagist上并由Composer使用, 但它使其他开发人员能够更快地发现和采用。

Platform packages(平台包)#

Composer有平台包, 这是在系统上安装一些东西的虚拟包, 但实际上不是由Composer安装的。这包括 php 本身、php 扩展和一些系统库.

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

  • hhvm 表示 HHVM 运行时的版本, 并允许您应用约束, 例如^2.3。

  • ext-<name> 允许您require PHP 扩展 (包括核心扩展)。在这里版本控制可能是相当不一致的, 所以把约束设置为*通常是个好主意。扩展包名称的一个示例是ext-gd.

  • lib-<name> 允许对 PHP 使用的库版本进行约束。以下是可用的: curl, iconv, icu, libxml, openssl, pcre, uuid, xsl。

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

Autoloading(自动加载)#

对于指定自动加载信息的库, 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');

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

{
    "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 部分获取更多信息.

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

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

除了 PSR-4 自动加载, Composer还支持 PSR-0、classmap 和文件自动加载。有关详细信息, 请参阅autoload。

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

注意: Composer提供了自己的自动加载器。如果你不想使用那个, 你可以包含vendor/composer/autoload_*.php 文件, 它返回关联数组, 使您可以配置自己的自动加载器.

← 介绍 | 库 →