Composer PHP依赖管理实战

Composer是2016年PHP生态中最重要的工具之一，由Nils Adermann和Jordi Boggiano开发，是PHP的依赖管理标准。它类似于Node.js的npm、Python的pip、Ruby的bundler，可以让你轻松地管理项目依赖，自动安装和更新第三方库，彻底改变了PHP项目的开发方式。

在Composer出现之前，PHP项目管理依赖非常痛苦。你需要手动下载第三方库，手动管理版本，手动处理依赖关系，手动配置自动加载。不同项目之间的依赖冲突更是让人头疼。Composer的出现，彻底解决了这些问题，让PHP项目的依赖管理变得简单、高效、标准化。

2016年，Composer已经成为PHP生态的标准工具。几乎所有的主流PHP框架（Laravel、Symfony、Yii、CodeIgniter等）都使用Composer管理依赖，Packagist（Composer的默认包仓库）上的包数量已经超过10万，月下载量超过数亿次。

作为一个PHP开发者，Composer是必备技能之一。今天就来系统地讲解Composer PHP依赖管理实战，从安装配置到高级用法，帮助你高效管理PHP项目的依赖。

一、Composer简介

1. 什么是Composer

Composer是PHP的依赖管理工具，它允许你声明项目所依赖的库，然后自动为你安装和更新这些库。

Composer的核心功能：

• 依赖管理：自动安装和更新项目依赖的第三方库
• 自动加载：自动生成PSR-4/PSR-0自动加载配置，不需要手动require
• 版本约束：灵活的版本约束机制，精确控制依赖版本
• 依赖解析：自动解析依赖之间的关系，解决版本冲突
• 脚本钩子：支持在安装/更新前后执行自定义脚本
• 包仓库：默认使用Packagist，也支持私有仓库和自定义仓库

2. Composer不是什么

• Composer不是包管理器（虽然大家都这么叫），它是依赖管理器。它管理的是项目级别的依赖，而不是系统级别的包。
• Composer不会全局安装包（默认），每个项目有独立的依赖，安装在项目的vendor目录下。
• Composer不是构建工具，它只管理依赖，不负责构建、测试、部署等（虽然可以通过脚本钩子实现部分功能）。

3. Composer的核心文件

• composer.json：项目的依赖声明文件，包含项目信息、依赖、自动加载配置、脚本等。
• composer.lock：锁定文件，记录所有依赖的确切版本，确保团队成员和部署环境使用相同的版本。
• vendor/：依赖安装目录，所有第三方库都安装在这里，应该加入.gitignore。
• vendor/autoload.php：自动生成的自动加载文件，在项目入口require即可。

二、安装与配置

1. 安装Composer

Linux/Mac安装：

# 下载安装脚本
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

# 验证安装脚本（可选）
php -r "if (hash_file('SHA384', 'composer-setup.php') === 'e115a8dc7871f15d853148a7fbac7da27d6c0030b848d9b3dc09e2a038fb3265c1c5c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"

# 运行安装脚本
php composer-setup.php

# 删除安装脚本
php -r "unlink('composer-setup.php');"

# 全局安装（移动到PATH目录）
mv composer.phar /usr/local/bin/composer
chmod +x /usr/local/bin/composer

Windows安装：

• 下载Composer-Setup.exe，运行安装程序，它会自动配置PATH。
• 或者手动下载composer.phar，创建composer.bat：

``bat @echo off php "%~dp0composer.phar" %* ``

验证安装：

composer --version
# Composer version 1.2.0 2016-07-18 11:25:04

2. 配置国内镜像

由于网络原因，国内访问Packagist可能很慢。2016年，可以配置国内镜像加速。

# 全局配置国内镜像（阿里云Composer镜像，2016年可用）
composer config -g repo.packagist composer https://packagist.phpcomposer.com

# 或者使用其他镜像
# composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

# 取消镜像配置
composer config -g --unset repos.packagist

也可以在项目的composer.json中配置：

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://packagist.phpcomposer.com"
    }
  ]
}

3. 全局配置

Composer的全局配置文件在~/.composer/config.json（Linux/Mac）或%APPDATA%/Composer/config.json（Windows）。

常用全局配置：

# 配置GitHub Token（增加GitHub API限额，安装GitHub上的包时需要）
composer config -g github-oauth.github.com <your-github-token>

# 配置HTTP基本认证
composer config -g http-basic.example.com username password

# 查看全局配置
composer config -g --list

三、composer.json详解

composer.json是Composer的核心配置文件，声明项目的依赖和配置。

1. 基本结构

{
  "name": "vendor/package-name",
  "description": "项目描述",
  "type": "project",
  "keywords": ["keyword1", "keyword2"],
  "homepage": "https://example.com",
  "license": "MIT",
  "authors": [
    {
      "name": "作者名",
      "email": "author@example.com",
      "homepage": "https://author.com",
      "role": "Developer"
    }
  ],
  "require": {
    "php": ">=5.6.0",
    "monolog/monolog": "^1.21"
  },
  "require-dev": {
    "phpunit/phpunit": "^5.4"
  },
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  },
  "autoload-dev": {
    "psr-4": {
      "Tests\\": "tests/"
    }
  },
  "scripts": {
    "test": "phpunit",
    "post-install-cmd": [
      "php -r \"echo '安装完成';\""
    ]
  },
  "config": {
    "preferred-install": "dist",
    "sort-packages": true
  }
}

2. 关键字段说明

• name：包名，格式为vendor/package，发布到Packagist时需要唯一。应用项目可以不填。
• description：包的简短描述。
• type：包的类型，可选值：library（默认，库）、project（项目）、metapackage（元包）、composer-plugin（Composer插件）。
• license：许可证，如MIT、Apache-2.0、GPL-2.0等。
• require：生产环境依赖，项目运行必需的包。
• require-dev：开发环境依赖，只在开发和测试时需要的包（如PHPUnit、调试工具）。
• autoload：自动加载配置。
• autoload-dev：开发环境的自动加载配置。
• scripts：脚本钩子，在特定事件执行自定义命令。
• config：Composer配置。
• repositories：自定义包仓库。
• minimum-stability：最低稳定性，可选值：dev、alpha、beta、RC、stable（默认）。
• prefer-stable：优先选择稳定版本。

3. 版本约束

Composer支持灵活的版本约束：

推荐使用^（脱字符）约束，它允许兼容的更新（不改变主版本号），是最安全和灵活的方式。

4. 自动加载配置

Composer支持多种自动加载方式：

{
  "autoload": {
    "psr-4": {
      "App\\": "src/",
      "App\\Models\\": "src/models/"
    },
    "psr-0": {
      "Old_Library_": "src/old/"
    },
    "classmap": [
      "src/classes/",
      "src/SomeClass.php"
    ],
    "files": [
      "src/helpers.php",
      "src/constants.php"
    ]
  }
}

• PSR-4：推荐使用，命名空间到目录的映射，自动加载性能好。
• PSR-0：旧标准，下划线转换为目录分隔符，不推荐新项目使用。
• classmap：扫描目录中的所有类，生成类映射表，适合不符合PSR标准的旧代码。
• files：每次请求都加载的文件，适合全局函数和常量。

修改autoload配置后，需要运行composer dump-autoload重新生成自动加载文件。

四、常用命令

1. init（初始化项目）

# 交互式创建composer.json
composer init

# 非交互式创建
composer init --name=vendor/package --description="描述" --license=MIT --require=monolog/monolog:^1.21

2. install（安装依赖）

# 根据composer.json和composer.lock安装依赖
composer install

# 只安装生产依赖，不安装require-dev
composer install --no-dev

# 不执行脚本钩子
composer install --no-scripts

# 不生成自动加载文件
composer install --no-autoloader

# 优先从源码安装（默认是dist）
composer install --prefer-source

composer install会优先读取composer.lock文件，安装锁定的确切版本，确保团队成员和部署环境使用相同的版本。如果没有composer.lock，则根据composer.json解析依赖并生成composer.lock。

3. update（更新依赖）

# 更新所有依赖到最新版本（符合版本约束）
composer update

# 更新指定包
composer update monolog/monolog

# 更新多个包
composer update monolog/monolog symfony/*

# 只更新composer.lock，不实际安装
composer update --lock

composer update会根据composer.json的版本约束，更新到最新的兼容版本，并更新composer.lock。注意：不要在生产环境运行composer update，应该运行composer install。

4. require（添加依赖）

# 添加生产依赖
composer require monolog/monolog

# 添加指定版本的依赖
composer require monolog/monolog:^1.21

# 添加开发依赖
composer require --dev phpunit/phpunit

# 添加多个依赖
composer require monolog/monolog symfony/http-foundation

composer require会自动更新composer.json，安装依赖，并更新composer.lock。

5. remove（移除依赖）

# 移除依赖
composer remove monolog/monolog

# 移除开发依赖
composer remove --dev phpunit/phpunit

6. search（搜索包）

# 搜索包
composer search monolog

# 只搜索包名
composer search monolog --only-name

7. show（查看包信息）

# 查看所有已安装的包
composer show

# 查看指定包的详细信息
composer show monolog/monolog

# 查看包的可用版本
composer show monolog/monolog --all

8. outdated（检查过时的包）

# 检查所有过时的包
composer outdated

# 只检查直接依赖
composer outdated --direct

# 严格模式（只显示有更新的）
composer outdated --strict

9. dump-autoload（重新生成自动加载）

# 重新生成自动加载文件
composer dump-autoload

# 优化自动加载（生产环境使用，性能更好）
composer dump-autoload --optimize

# 权威类映射（优化，但是添加新类需要重新生成）
composer dump-autoload --classmap-authoritative

生产环境建议使用--optimize优化自动加载，提升性能。

10. diagnose（诊断）

# 诊断Composer环境
composer diagnose

检查PHP版本、openssl、git、http连接等是否正常。

11. self-update（自更新）

# 更新Composer自身到最新版本
composer self-update

# 更新到指定版本
composer self-update 1.2.0

# 回滚到上一个版本
composer self-update --rollback

五、Packagist使用

Packagist是Composer的默认包仓库，是PHP包的中央仓库。

1. 搜索和浏览包

• 访问https://packagist.org搜索和浏览包
• 查看包的详细信息、版本、下载量、依赖等
• 每个包都有安装命令，直接复制运行即可

2. 发布自己的包

1. 在GitHub（或其他Git仓库）创建项目，包含composer.json
2. 确保composer.json中的name字段格式正确（vendor/package）
3. 登录Packagist，点击"Submit"，输入项目的Git仓库URL
4. Packagist会自动抓取包信息
5. 设置GitHub Service Hook，让Packagist在代码推送时自动更新
6. 发布版本：在Git中打标签（如v1.0.0），Packagist会自动创建版本

3. 包版本管理

• 使用Git标签管理版本，标签名应该是有效的版本号（如1.0.0、v1.0.0）
• 遵循语义化版本（SemVer）：主版本号.次版本号.修订号

- 主版本号：不兼容的API修改 - 次版本号：向下兼容的功能性新增 - 修订号：向下兼容的问题修正

• dev-master对应master分支的最新代码
• 分支名需要加dev-前缀（如dev-develop）

六、私有仓库

对于公司内部的私有包，可以使用私有仓库。

1. Satis（自建私有仓库）

Satis是Composer官方的静态私有仓库生成工具，可以自建私有Packagist。

# 安装Satis
composer create-project composer/satis --stability=dev --keep-vcs

# 创建satis.json配置
{
  "name": "My Private Repository",
  "homepage": "http://satis.example.com",
  "repositories": [
    { "type": "vcs", "url": "git@github.com:vendor/package1.git" },
    { "type": "vcs", "url": "git@github.com:vendor/package2.git" }
  ],
  "require-all": true
}

# 生成仓库
php bin/satis build satis.json web/

# 部署到Web服务器

2. Toran Proxy

Toran Proxy是Jordi Boggiano（Composer作者）开发的私有仓库和代理工具，功能更强大，但是商业软件（有免费版）。

3. 直接使用VCS仓库

可以在composer.json中直接指定Git仓库，不需要搭建私有仓库：

{
  "repositories": [
    {
      "type": "vcs",
      "url": "git@github.com:vendor/private-package.git"
    }
  ],
  "require": {
    "vendor/private-package": "dev-master"
  }
}

支持的VCS类型：git、svn、hg。

七、最佳实践

1. 提交composer.lock

• 应用项目：应该提交composer.lock到版本控制，确保团队成员和部署环境使用相同的版本。
• 库项目：不应该提交composer.lock，因为库需要兼容多个版本的依赖。

2. 忽略vendor目录

vendor目录应该加入.gitignore，不提交到版本控制。每个开发者运行composer install安装自己的依赖。

# .gitignore
/vendor/
/composer.phar

3. 使用require-dev分离开发依赖

开发和测试工具（如PHPUnit、PHP_CodeSniffer、调试工具）应该放在require-dev中，生产环境使用composer install --no-dev不安装这些包，减少体积和安全风险。

4. 优化自动加载

生产环境使用composer dump-autoload --optimize优化自动加载，提升性能。也可以在install时使用--optimize-autoloader选项。

5. 版本约束使用^

推荐使用^（脱字符）作为版本约束，它允许兼容的更新，是最安全和灵活的方式。避免使用*或dev-master，可能导致不兼容的更新。

6. 定期更新依赖

定期运行composer outdated检查过时的依赖，及时更新到新版本，获取安全补丁和新功能。但是更新前要测试，确保兼容性。

7. 脚本钩子

利用Composer的脚本钩子自动化常见任务：

{
  "scripts": {
    "test": "phpunit",
    "lint": "phpcs src/",
    "fix": "phpcbf src/",
    "post-install-cmd": [
      "php -r \"copy('.env.example', '.env');\""
    ],
    "post-update-cmd": [
      "php artisan cache:clear"
    ]
  }
}

运行自定义脚本：

composer test
composer run-script lint

8. 配置国内镜像

国内开发者建议配置国内镜像，加速依赖下载。

八、常见问题与排错

1. 内存不足

Composer有时会消耗大量内存，特别是处理大型项目时。

# 增加PHP内存限制
php -d memory_limit=-1 composer.phar install

# 或者在php.ini中设置
memory_limit = -1

2. 版本冲突

当多个依赖需要同一个包的不同版本，且版本不兼容时，会出现版本冲突。

解决方法：

• 查看冲突信息，了解哪些包需要哪些版本
• 更新冲突的包到兼容的版本
• 使用composer why和composer why-not查看依赖关系

``bash composer why monolog/monolog # 查看谁依赖了monolog composer why-not monolog/monolog ^2.0 # 查看为什么不能安装2.0版本 ``

• 如果无法解决，可以考虑使用替代包或降级版本

3. 安装超时

网络问题导致安装超时。

解决方法：

• 配置国内镜像
• 增加超时时间：composer config -g process-timeout 3000
• 使用--prefer-dist从压缩包安装（比源码快）
• 重试安装

4. 认证失败

访问私有仓库或GitHub API时认证失败。

解决方法：

• 配置GitHub Token：composer config -g github-oauth.github.com <token>
• 配置HTTP基本认证：composer config -g http-basic.example.com username password
• 检查SSH密钥配置（访问Git仓库时）

5. 自动加载不生效

修改代码后自动加载找不到类。

解决方法：

• 运行composer dump-autoload重新生成自动加载
• 检查命名空间和目录结构是否符合PSR-4
• 检查composer.json中的autoload配置是否正确
• 确认在入口文件中require了vendor/autoload.php

6. composer.lock不同步

团队成员的composer.lock不一致，导致版本不同。

解决方法：

• 确保composer.lock提交到版本控制
• 团队成员使用composer install而不是composer update
• 更新依赖后，提交更新后的composer.lock
• 部署时使用composer install确保版本一致

总结

Composer是2016年PHP生态中最重要的工具之一，是PHP的依赖管理标准。它让PHP项目的依赖管理变得简单、高效、标准化，彻底改变了PHP项目的开发方式。

本文从Composer简介、安装配置、composer.json详解、常用命令、自动加载、版本约束、Packagist使用、私有仓库、最佳实践、常见问题排错等方面，系统讲解了Composer PHP依赖管理实战。

Composer学习的核心要点：

1. 理解composer.json和composer.lock的作用
2. 掌握常用命令：install、update、require、remove、dump-autoload
3. 理解版本约束，推荐使用^（脱字符）
4. 配置自动加载（PSR-4），优化自动加载（生产环境）
5. 使用require-dev分离开发依赖
6. 配置国内镜像加速
7. 提交composer.lock（应用项目），忽略vendor目录
8. 定期更新依赖，使用composer outdated检查

Composer是PHP开发者的必备技能，掌握Composer能让你的PHP开发效率大幅提升。希望本文能帮助你更好地使用Composer，高效管理PHP项目的依赖。