基本用法

简介

在我们的基本使用介绍中，我们将安装monolog/monolog，这是一个日志记录库。如果您尚未安装Composer，请参考入门章节。

**注意：**为简单起见，本介绍将假设您已执行Composer的本地安装。

`composer.json`：项目设置

要在你的项目中开始使用Composer，你只需要一个composer.json文件。这个文件描述了项目的依赖项，也可能包含其他元数据。它通常应该放在项目/版本控制系统（VCS）仓库的最顶层目录中。从技术上讲，你可以在任何地方运行Composer，但如果你想将包发布到Packagist.org，系统必须能在你的版本控制系统仓库的顶层找到这个文件。

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。

了解更多关于发布包和包命名的信息。（请注意，你也可以指定“平台包”作为依赖项，这样你就可以要求特定版本的服务器软件。请参见下面的平台包</b1。）

包版本约束

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

请阅读版本以获取有关版本、版本之间的关系以及版本约束的更深入信息。

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

当Composer在Packagist.org或您指定的仓库中找到合适的包时，它会使用该包版本控制系统（即分支和标签）的版本控制功能，尝试找到与您指定的版本约束最匹配的版本。请务必阅读版本文章中关于版本和包解析的内容。

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

如果你尝试使用某个包的开发版、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`文件提交到版本控制

将此文件提交到版本控制非常重要，因为这会确保任何搭建该项目的人都使用与你完全相同版本的依赖项。你的持续集成服务器、生产机器、团队中的其他开发人员，所有事物和人员都将运行在相同的依赖项上，这能减少仅影响部分部署的潜在漏洞。即使你是独自开发，六个月后重新安装该项目时，你也可以确信所安装的依赖项仍然能正常工作，即便在此期间这些依赖项已经发布了许多新版本。（请参见下方关于使用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未更新，那么执行install命令时，Composer将显示警告。

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

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

Packagist

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

如果你访问Packagist.org网站</b0，你可以浏览和搜索包。

建议任何使用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文件，这些文件会返回关联数组，供您配置自己的自动加载器。