3、Composer依赖管理：Composer安装与使用、自动加载机制、私有包仓库搭建

聊到PHP项目，绕不开的就是Composer。说实话，在我刚入行那会儿，PHP的依赖管理还是一片混乱——大家要么手动下载库文件，要么用PEAR这种老古董。直到Composer出现，整个生态才算真正成熟起来。今天我就把Composer这块掰开揉碎了讲清楚。

3.1 Composer的安装与基础使用

安装Composer其实很简单。我个人习惯用全局安装的方式，这样在任何项目里都能直接调用。

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

# 验证签名（我建议这一步别跳过）
php -r "if (hash_file('sha384', 'composer-setup.php') === 'your-hash-here') { echo 'Installer verified'; }"

# 安装到全局
php composer-setup.php --install-dir=/usr/local/bin --filename=composer

装完之后跑一下 composer --version，看到版本号就说明搞定了。嗯，这里要注意：Windows用户记得把Composer的路径加到环境变量里，不然每次都要写全路径，挺烦的。

小技巧： 我习惯把Composer的镜像源换成国内的，速度能快不少。用阿里云的镜像，执行 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 就行。

3.2 composer.json与依赖声明

每个PHP项目都需要一个 composer.json 文件。它就像项目的「购物清单」，告诉Composer你需要哪些依赖。

{
    "name": "your-vendor/your-project",
    "description": "一个示例项目",
    "require": {
        "php": ">=8.0",
        "monolog/monolog": "^2.0",
        "guzzlehttp/guzzle": "^7.0"
    },
    "require-dev": {
        "phpunit/phpunit": "^9.0"
    }
}

这里有个坑，我踩过好几次：版本约束里的 ^ 和 ~ 含义不同。^2.0 表示允许2.0到3.0之间的任何版本（不包含3.0），而 ~2.0 只允许2.0.x的小版本更新。你想想看，如果不搞清楚这个，项目可能莫名其妙就升级了不兼容的版本。

3.3 自动加载机制

Composer最牛的地方之一，就是它的自动加载机制。说白了，你只要在项目入口文件里加一行代码，所有依赖的类就都能自动找到了。

require __DIR__ . '/vendor/autoload.php';

为什么会这么神奇？Composer会根据 composer.json 里的配置，生成一个 vendor/composer/autoload_classmap.php 文件，把每个类名和它的文件路径一一对应起来。当你用到一个类时，自动加载器会直接找到对应的文件并加载。

我个人习惯在项目里用PSR-4规范来组织代码。举个例子：

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

这样，命名空间 App\Controller\UserController 就会自动映射到 src/Controller/UserController.php。我在项目中遇到过有人把命名空间写错大小写，结果类死活加载不上——Linux系统对大小写敏感，Windows反而不报错，一上线就崩了。

重要： 每次修改 autoload 配置后，记得执行 composer dump-autoload 重新生成自动加载文件。我曾经忘了这步，排查了半天才发现是缓存没更新。

3.4 私有包仓库搭建

很多公司会有自己的私有包，比如内部封装的SDK、公共工具库。这些包不能公开到Packagist上，就需要搭建私有仓库。

我推荐用 Satis 或者 Private Packagist。Satis是开源的，适合小团队；Private Packagist是商业产品，功能更全。

用Satis搭建私有仓库

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

# 创建配置文件 satis.json
{
    "name": "my-company/private-repo",
    "homepage": "http://packages.mycompany.com",
    "repositories": [
        { "type": "vcs", "url": "git@gitlab.mycompany.com:php-utils.git" }
    ],
    "require-all": true
}

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

生成之后，把 public/ 目录部署到你的Web服务器上。然后在项目里这样引用：

{
    "repositories": [
        {
            "type": "composer",
            "url": "http://packages.mycompany.com"
        }
    ],
    "require": {
        "my-company/php-utils": "^1.0"
    }
}
避坑指南： 我曾经把私有仓库的认证信息直接写在 composer.json 里，结果不小心提交到了公开仓库。正确的做法是用环境变量或者 auth.json 文件来管理认证信息。

3.5 版本锁定与更新策略

项目上线后，依赖版本一定要锁定。Composer用 composer.lock 文件来记录当前安装的确切版本。我建议把这个文件也提交到Git里，这样所有开发者和生产环境用的都是同一套依赖。

命令 作用 使用场景
composer install 根据 composer.lock 安装依赖 部署、新成员拉取项目
composer update 更新依赖到最新版本并更新lock文件 开发阶段升级依赖
composer require 添加新依赖 引入新包

嗯，这里要特别提醒：生产环境部署时，永远用 composer install --no-dev。开发依赖（比如PHPUnit）不应该出现在生产环境里，既占空间又有安全风险。

3.6 实战经验总结

最后分享几个我这些年积累的经验：

  • 定期更新依赖：别等到项目快上线了才想起来更新，那时候出兼容性问题就来不及了。我一般每个月跑一次 composer outdated 看看哪些包需要更新。
  • 用好脚本钩子：Composer支持在安装、更新等事件前后执行自定义脚本。比如我习惯在 post-install-cmd 里自动清理缓存、生成配置文件。
  • 注意PHP版本兼容：有些包只支持特定PHP版本。我在项目中遇到过因为PHP版本太低，导致最新版依赖装不上的情况。解决办法是在 composer.json 里明确声明PHP版本要求。
我的习惯： 每次提交代码前，我会在CI流程里加一步 composer validate，检查 composer.json 格式是否正确。这个小动作帮我避免过好几次因为格式错误导致的构建失败。

Composer这东西，用好了能极大提升开发效率。说白了，它不只是个包管理器，更是PHP项目工程化的基石。从依赖管理到自动加载，再到私有仓库，每一步都值得你花时间吃透。

← 上一章 📖 返回目录 下一章 →