PHP Composer：依赖管理与 autoload

PHP 项目在开发过程中常常需要引入第三方库，比如数据库操作、日志记录、HTTP 客户端等。手动下载、解压、配置路径不仅繁琐，还容易出错。Composer 是 PHP 的官方依赖管理工具，能自动下载所需库、解决版本冲突，并通过 autoload（自动加载）机制让你无需手动 include 或 require 文件。

安装 Composer

下载 Composer 安装脚本到本地：

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

验证 脚本的 SHA-384 哈希值（可选但推荐）：

php -r "if (hash_file('sha384', 'composer-setup.php') === 'dac665fdc30fdd8ec78b38b9800061b4150413ff2e3b6f8d10723e67666c49') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"

执行 安装脚本：

php composer-setup.php

移除 安装脚本：

php -r "unlink('composer-setup.php');"

安装完成后，会在当前目录生成一个 composer.phar 文件。你可以将其全局移动以便在任何目录使用：

sudo mv composer.phar /usr/local/bin/composer

现在，在终端输入 composer --version，如果显示版本号，说明安装成功。

初始化项目并声明依赖

进入你的 PHP 项目根目录（若无，则先创建一个空文件夹），执行初始化命令：

composer init

该命令会交互式地引导你填写项目信息，包括包名、描述、作者、最低稳定版本等。最关键的是 添加依赖。例如，你想使用 monolog/monolog 这个日志库：

1. 当提示 “Would you like to define your dependencies (require) interactively [yes]?” 时，输入 yes。
2. 输入依赖名称：monolog/monolog
3. 输入版本约束（直接回车表示使用最新稳定版）

完成后，项目根目录会生成一个 composer.json 文件，内容类似：

{
    "name": "yourname/your-project",
    "description": "A sample PHP project",
    "require": {
        "monolog/monolog": "^3.0"
    }
}

其中 "monolog/monolog": "^3.0" 表示允许安装 3.x 系列的最新兼容版本（如 3.1、3.2，但不包括 4.0）。

安装依赖

运行以下命令，Composer 会根据 composer.json 自动下载所有依赖及其子依赖到 vendor/ 目录：

composer install

首次运行后，还会生成一个 composer.lock 文件，它锁定当前安装的确切版本号，确保团队成员或生产环境安装完全一致的依赖。

注意：composer install 在存在 composer.lock 时会严格按锁文件安装；若要更新依赖到符合 composer.json 的最新版本，应使用 composer update。

使用 autoload 自动加载类

Composer 不仅下载代码，还自动生成一个自动加载器。你只需在项目入口文件（如 index.php）中 包含 自动生成的 autoload 文件：

<?php
require_once __DIR__ . '/vendor/autoload.php';

// 现在可以直接使用 Monolog 的类，无需手动 require
$log = new Monolog\Logger('name');
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
$log->warning('This is a warning!');

关键点：不需要写 require 'vendor/monolog/monolog/src/Monolog/Logger.php'。Composer 的 autoload 机制会根据类名自动找到对应文件并加载。

autoload 的工作原理

Composer 支持多种自动加载方式，最常见的是 PSR-4（推荐）和 classmap。

当你在 composer.json 中定义命名空间映射时，例如：

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

这表示：所有以 App\ 开头的类，其源文件位于 src/ 目录下，且目录结构与命名空间一致。例如：

• 类 App\Controller\UserController 对应文件 src/Controller/UserController.php
• 类 App\Model\Post 对应文件 src/Model/Post.php

修改 composer.json 后，必须 重新生成 autoload 文件：

composer dump-autoload

或者更常用的方式是在添加新类后直接运行：

composer install
# 或
composer update

这些命令会自动触发 autoload 重建。

查看已安装的依赖

列出所有已安装的包及其版本：

composer show

查看某个包的详细信息（如 monolog/monolog）：

composer show monolog/monolog

更新与移除依赖

更新所有依赖到符合 composer.json 约束的最新版本：

composer update

更新特定依赖（如只更新 monolog）：

composer update monolog/monolog

移除不再需要的依赖：

composer remove monolog/monolog

该命令会从 composer.json 和 composer.lock 中删除条目，并清理 vendor/ 目录中的相关文件。

生产环境优化

在部署到服务器时，为提升性能，启用 autoload 优化：

composer install --optimize-autoloader --no-dev

• --optimize-autoloader：生成 classmap 缓存，加快类查找速度。
• --no-dev：不安装开发依赖（如 PHPUnit、PHPStan），仅安装 require 中的包，而非 require-dev 中的。

常见问题排查

1. 类未找到（Class not found）
   检查：

   • 是否已 require 'vendor/autoload.php'？
   • 类名与文件路径是否符合 PSR-4 规则（注意大小写）？
   • 是否运行了 composer dump-autoload？

2. 依赖冲突
   Composer 会报错提示版本不兼容。尝试：

   • 放宽版本约束（如将 "^2.0" 改为 "^2.0 || ^3.0"）
   • 使用 composer why-not vendor/package version 查看冲突原因

3. 国内下载慢
   配置阿里云镜像加速：

   composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

依赖声明最佳实践

例如，一个典型项目的 composer.json 可能如下：

{
    "name": "myapp/blog",
    "require": {
        "slim/slim": "^4.0",
        "doctrine/dbal": "^3.0"
    },
    "require-dev": {
        "phpunit/phpunit": "^10.0",
        "squizlabs/php_codesniffer": "^3.7"
    },
    "autoload": {
        "psr-4": {
            "MyApp\\": "src/"
        }
    }
}

执行 composer install --no-dev 部署到生产环境时，PHPUnit 和 PHPCS 不会被安装，减少体积和安全风险。

创建一个新项目时，也可以直接基于现有模板：

composer create-project slim/slim-skeleton my-api

该命令会自动下载 slim/slim-skeleton 并初始化为名为 my-api 的项目，包含完整的依赖和 autoload 配置。

所有依赖管理和自动加载的核心，都围绕 composer.json、vendor/ 目录和 vendor/autoload.php 展开。掌握这三者的关系，就能高效构建可维护的 PHP 应用。