第 15 章 — Composer
第 15 章 — Composer：依赖管理、自动加载与私有包
15.1 Composer 概述
Composer 是 PHP 的标准包管理器，类似于 Node.js 的 npm 或 Python 的 pip。
# 验证安装
composer --version
# Composer version 2.8.x
# 诊断
composer diagnose
15.2 composer.json 核心字段
{
"name": "vendor/project",
"description": "项目描述",
"type": "project",
"license": "MIT",
"minimum-stability": "stable",
"prefer-stable": true,
"require": {
"php": ">=8.3",
"monolog/monolog": "^3.0",
"guzzlehttp/guzzle": "^7.0",
"vlucas/phpdotenv": "^5.6"
},
"require-dev": {
"phpunit/phpunit": "^11.0",
"phpstan/phpstan": "^2.0",
"friendsofphp/php-cs-fixer": "^3.0"
},
"autoload": {
"psr-4": {
"App\\": "src/"
},
"files": ["src/helpers.php"]
},
"autoload-dev": {
"psr-4": {
"Tests\\": "tests/"
}
},
"scripts": {
"test": "phpunit",
"analyse": "phpstan analyse src --level=9",
"cs-fix": "php-cs-fixer fix",
"build": [
"@cs-fix",
"@analyse",
"@test"
]
},
"config": {
"sort-packages": true,
"allow-plugins": {}
}
}
15.3 版本约束
| 运算符 | 示例 | 说明 |
|---|---|---|
^ | ^2.0 | 等于 >=2.0.0 <3.0.0（推荐） |
~ | ~2.0.0 | 等于 >=2.0.0 <2.1.0 |
* | * | 任意版本 |
>= | >=2.0 | 大于等于 |
2.0.* | 2.0.* | 通配符 |
2.0|2.1 | 2.0|2.1 | 或运算 |
最佳实践
{
// ✅ 推荐：使用 ^ 允许补丁和小版本更新
"monolog/monolog": "^3.0",
// ⚠️ 注意：~ 范围更窄
"package": "~2.1.0", // 只允许 2.1.x
// ❌ 不推荐：锁定具体版本
"package": "2.1.3"
}
15.4 常用命令
15.4.1 依赖管理
# 安装所有依赖（根据 composer.lock）
composer install
# 添加依赖
composer require guzzlehttp/guzzle
composer require --dev phpunit/phpunit
# 移除依赖
composer remove guzzlehttp/guzzle
# 更新依赖
composer update # 更新所有
composer update monolog/monolog # 更新指定包
composer update --dry-run # 预览更新
# 查看已安装
composer show
composer show --tree
composer show guzzlehttp/guzzle
# 查看过时包
composer outdated
composer outdated --direct # 只看直接依赖
# 校验
composer validate
15.4.2 自动加载
# 重新生成自动加载映射
composer dump-autoload
# 生产优化（生成优化的类映射）
composer dump-autoload --optimize
# 等价于 --optimize-autoloader
# 查看自动加载映射
composer dump-autoload --dry-run
15.5 PSR-4 自动加载
15.5.1 基本配置
{
"autoload": {
"psr-4": {
"App\\": "src/",
"App\\Tests\\": "tests/"
}
}
}
项目结构：
src/
├── Controllers/
│ └── UserController.php → App\Controllers\UserController
├── Models/
│ └── User.php → App\Models\User
├── Services/
│ └── UserService.php → App\Services\UserService
└── Exceptions/
└── AppException.php → App\Exceptions\AppException
15.5.2 files 自动加载
{
"autoload": {
"files": ["src/helpers.php", "src/constants.php"]
}
}
<?php
// src/helpers.php — 全局辅助函数
if (!function_exists('env')) {
function env(string $key, mixed $default = null): mixed
{
return $_ENV[$key] ?? getenv($key) ?: $default;
}
}
if (!function_exists('dd')) {
function dd(mixed ...$vars): never
{
foreach ($vars as $var) {
var_dump($var);
}
exit(1);
}
}
15.5.3 classmap 自动加载
{
"autoload": {
"classmap": ["src/legacy/", "src/generated/"]
}
}
classmap 会扫描目录下所有 PHP 文件并生成类映射表，适用于不符合 PSR-4 规范的旧代码。
15.6 类型映射与平台包
{
"require": {
"php": ">=8.3",
"ext-pdo": "*",
"ext-mbstring": "*",
"ext-json": "*",
"ext-curl": "*",
"ext-intl": "*"
}
}
# 检查平台要求
composer check-platform-reqs
# 忽略平台要求（不推荐）
composer install --ignore-platform-reqs
15.7 脚本（Scripts）
{
"scripts": {
"test": "phpunit --colors=always",
"test:coverage": "phpunit --coverage-html=coverage/",
"analyse": "phpstan analyse src --level=9",
"cs-check": "php-cs-fixer fix --dry-run --diff",
"cs-fix": "php-cs-fixer fix",
"post-install-cmd": [
"@php -r \"file_put_contents('.version', time());\""
],
"build": [
"@cs-fix",
"@analyse",
"@test"
]
}
}
composer test
composer run analyse
composer build
事件钩子
| 事件 | 触发时机 |
|---|---|
pre-install-cmd | install 之前 |
post-install-cmd | install 之后 |
pre-update-cmd | update 之前 |
post-update-cmd | update 之后 |
post-autoload-dump | dump-autoload 之后 |
pre-archive-cmd | archive 之前 |
15.8 私有包与自定义仓库
15.8.1 私有 Composer 仓库
{
"repositories": [
{
"type": "composer",
"url": "https://packages.mycompany.com",
"options": {
"http": {
"header": ["Authorization: Bearer TOKEN"]
}
}
}
]
}
15.8.2 Git 仓库
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/mycompany/private-package"
}
],
"require": {
"mycompany/private-package": "dev-main"
}
}
15.8.3 路径仓库（本地开发）
{
"repositories": [
{
"type": "path",
"url": "../my-library"
}
],
"require": {
"mycompany/my-library": "*"
}
}
15.8.4 私有 Packagist
# 使用 Private Packagist（商业服务）
composer config repositories.private-packagist composer https://repo.packagist.com/mycompany/
15.9 Composer 插件生态
| 插件 | 用途 |
|---|---|
composer-merge-plugin | 合并多个 composer.json |
composer-patches | 应用补丁 |
bamarni/composer-bin-plugin | 二进制依赖隔离 |
ergebnis/composer-normalize | 规范化 composer.json |
roave/security-advisories | 安全漏洞检查 |
# 安全审计
composer audit
# 漏洞检查
composer show --no-dev --direct | while read pkg ver; do
composer audit "$pkg"
done
15.10 生产环境优化
# 生产构建
composer install --no-dev --optimize-autoloader --no-interaction --prefer-dist
# Docker 中的多阶段构建
# ... (见第 25 章)
# 清除缓存
composer clear-cache
15.11 业务场景：Monorepo
// 根目录 composer.json
{
"name": "mycompany/monorepo",
"require": {},
"scripts": {
"test:all": [
"cd packages/api && composer test",
"cd packages/shared && composer test"
]
}
}
// packages/api/composer.json
{
"name": "mycompany/api",
"require": {
"mycompany/shared": "dev-main"
},
"repositories": [
{
"type": "path",
"url": "../shared"
}
]
}
15.12 扩展阅读
上一章：第 14 章 — 生成器 下一章：第 16 章 — 错误处理