Composer用法详解

原文地址：https://getcomposer.org/doc/01-basic-usage.md
做了部分内容和格式的优化调整。
2022.11

1. 介绍

我们将通过安装一个monolog/monolog日志库，来介绍composer的基本用法，如果您还没有安装 Composer，请参阅 简介一章。

2. composer.json文件

要开始在您的项目中使用 Composer，您只需要一个composer.json 文件。该文件描述了项目的依赖关系，也可能包含其他元数据。它通常应该放在项目/VCS 存储库的最顶层目录中。

从技术上讲，您可以在任何地方运行 Composer，但如果您想将包发布到 Packagist.org，它必须能够在您的 VCS 存储库顶部找到该文件。

2.1 ‘require’ 关键字

在composer.json中需要指定的第一件事是 require 关键字。告诉 Composer 您的项目依赖于哪些包。

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

如你所见，require包含一个键值对，把对象的包名称（例如monolog/monolog）映射到版本号（例如2.0.*）。

Composer使用这些信息，在使用’repositories’关键字注册的包存储库中，或者默认的包存储库Packagist.org中，搜索正确的文件集。在上面的示例中，由于composer.json文件中没有注册其他存储库 ，因此假定该monolog/monolog包已在 Packagist.org 上注册。阅读更多有关 Packagist和 存储库的信息，参考：https://getcomposer.org/doc/05-repositories.md。

3. Package names 包名称

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

参阅有关发布包和包命名的更多信息。

3.1 Package version constraints 包版本限制

在上述示例中，我们请求带有版本约束的 Monolog 包 2.0.*。这意味着2.0开发分支中的任何版本（如2.0.9）。

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

注意：默认情况下，在 VCS 中搜索有效的软件包版本时，只会考虑稳定版本。

4 Install dependencies 安装依赖项

4.1 update

在最初为你的项目安装定义的依赖项时，应该运行 update命令：
php composer.phar update

这将使 Composer 做两件事：

• 解析composer.json文件中列出的所有依赖项，并将所有包及其确切版本写入composer.lock文件，将项目锁定到这些特定版本。
  您应该将该composer.lock文件提交到您的项目存储库，以便所有从事该项目的人员都被锁定到相同版本的依赖项。这是update命令的主要作用。
• 然后隐式运行install命令。这会将依赖项的文件下载到vendor项目的目录中，这个vendor 目录是项目中所有第三方代码的通用位置。
  在上面的示例中，您会得到 vendor/monolog/monolog/目录， 由于 Monolog 依赖于psr/log，所以也会同时得到vendor/psr/log目录.

提示：如果你在项目中使用git，而且你不希望将所有第三方代码添加到版本化存储库中，你可以根据需要在.gitignore中添vendor。

4.2 对 composer.lock 文件进行版本控制

将此文件提交到版本控制（如git，SVN等）很重要，因为它会让项目的所有人使用与您正在使用的依赖项完全相同的版本。您的 CI 服务器、生产机器、您团队中的其他开发人员，所有的地方都运行在相同的依赖项上，这减少了部署错误的可能性。
任何时间重新安装项目时，您也可以确信安装的依赖项仍然有效，即使您的依赖项发布了许多新版本。

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

4.3 从 composer.lock文件中安装

php composer.phar install

如果您的项目文件夹中已经有一个composer.lock文件，则意味着您之前运行过update命令，或者项目中的其他人运行过update ，并且已经将composer.lock文件提交给项目（的版本控制）。

无论哪种方式，在composer.lock文件存在时运行install，都会解析并安装您在composer.json中列出的所有依赖项，但 Composer 只会使用composer.lock中列出的确切版本，以确保包版本对于处理您的项目的每个人都是一致的。

因此，您将拥有 composer.json文件请求的所有依赖项，但它们可能并非都是最新的可用版本（文件中列出的某些依赖项composer.lock可能在文件创建后发布了较新的版本）。这是设计使然，它确保您的项目不会因为依赖项的意外更改而中断。

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

5. 将依赖项更新到最新版本

如上所述，composer.lock文件会阻止您自动获取最新版本的依赖项。要更新到最新版本，请使用update命令。

php composer.phar update

这个命令将获取最新的匹配版本（根据您的composer.json文件），然后并使用新版本更新锁定文件（即生成新的 composer.lock文件）

注意：在composer.json做了更改但composer.lock文件没有更新的情况下，执行了intall命令时，Compser会显示一个警告，告知可能会影响对依赖项的解析。

如果你只想安装、升级或删除一个依赖项，你可以明确地将其列为参数：
php composer.phar update monolog/monolog [...]

6. Packgist 存储库

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

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

任何使用 Composer 的开源项目都被推荐在 Packagist 上发布它们的包。一个不在 Packagist 上对库可以被 Composer 使用，但放在Packagist上之后，可以让其他开发人员更快地发现和采用。

7. Platform packages 平台包

Composer 有‘平台包’的概念，它们是安装在系统上，但实际上不能由 Composer 安装的虚拟包。这包括 PHP 本身、PHP 扩展和一些系统库。

• php表示用户的 PHP 版本，允许您应用约束，例如^7.1 要求require 64 位版本的 php，您可以require php-64bit的包。
• hhvm表示 HHVM 运行时的版本，允许您应用对HHVM的约束，例如，^2.3.
• ext-<name>允许您要求 PHP 扩展（包括核心扩展）。此处的版本控制可能非常不一致，因此建议将约束设置为*。一个扩展包名称的举例：ext-gd.
• lib-<name>允许对 PHP 使用的Library库版本进行约束。以下是一些可用的库名称：curl, iconv, icu, libxml, openssl, pcre, uuid, xsl。

您可以使用如下指令]获取本地可用平台包的列表：
[composer show --platform

8. Autoloading 自动加载

对于指定自动加载信息的库，Composer 生成一个 vendor/autoload.php文件。您可以在代码中require此文件，然后开始使用这些库提供的类，而无需任何额外工作：

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 将为命名空间注册一个PSR-4自动加载器Acme。

您定义从命名空间到目录的映射。该src目录将位于您的项目根目录中，与该vendor目录处于同一级别。示例文件名将src/Foo.php包含一个Acme\Foo类。
以上代码中定义了一个从命名空间（psr-4）到目录（src/）的映射。src目录在项目根目录下，与vendor目录同级。其中应该有一个文件（例如是src/Foo.php），包含一个Acme\Foo的类。

在composer.json文件添加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文件，它返回关联数组，允许你配置你自己的自动加载器。