重构老旧遗留：引入Composer循序渐进实现代码现代化迁移

重构老旧遗留：引入Composer循序渐进实现代码现代化迁移

为什么不能直接在旧项目里执行 composer install

这事儿得从根儿上讲。绝大多数“上了年纪”的PHP项目——比如2010年代初的CodeIgniter 2.x、Zend Framework 1，或者各种自研的MVC框架——压根儿就没有composer.json这回事，更别提遵循PSR-0/4的自动加载规范了。你直接上去敲composer install，结果大概率是报错Could not find a composer.json file。这还算好的，更棘手的是，旧代码里那些密密麻麻的require_once ‘xxx.php’，很可能会和Composer自己的autoloader打起架来，导致类重复声明，或者干脆找不着北。

所以，问题的关键不在于“能不能装”，而在于“装了之后，谁来加载、怎么和现有的老逻辑和平共处”。我们的目标不是让Composer的加载器去取代旧系统，而是先让它们俩能共存。

• 第一步，得手动创建一个最小可用的composer.json文件。先别急着引入任何第三方包，核心是声明autoload部分，用psr-4或者classmap都行。
• 第二步，在项目的入口文件（通常是index.php）里，务必确保require ‘vendor/autoload.php’在所有旧的require/require_once语句之前执行。顺序错了，旧代码可能就把同名类给提前加载了，那Composer的自动加载就形同虚设了。
• 第三步，如果老项目里还散落着一些全局函数或者静态工具类，可以用files这种autoload类型来引入，比如这样配置："files": ["helpers/common_helper.php"]。

如何让旧类名被Composer自动加载识别

接下来是个现实难题：老项目里的类名，要么是下划线风格的My_Class_Name，要么干脆就没有命名空间。而Composer默认只认PSR-4格式（Vendor\Package\ClassName）。把成千上万个类名全改一遍？不现实，风险也太高。

这时候，更靠谱的办法是请出classmap生成器。它不关心你的命名规则，它的工作就是扫描你指定的目录，把每个.php文件里声明的class，原封不动地记录到vendor/composer/autoload_classmap.php文件里去。

• 在composer.json里添加类似这样的配置："classmap": ["application/libraries/", "application/models/"]（具体路径根据你的项目结构调整）。
• 然后运行命令：composer dump-autoload -o，生成优化后的classmap。
• 怎么验证成功了？写个简单的测试脚本，var_dump(class_exists(‘User_model’));，如果返回true，并且这个类的实例能正常调用方法，那就妥了。
• 需要留意的是，classmap不支持动态新增文件。以后每增加或删除一个类文件，都得重新运行一遍dump-autoload命令。

逐步替换旧依赖：从 monolog/monolog 这类无侵入工具开始

改造老系统，最忌讳的就是“大动干戈”。千万别一上来就动数据库抽象层或者路由系统这些核心部件。优先选择的，应该是那些“只做加法、不改逻辑”的工具类库——它们不改变请求的生命周期，不接管输出，只是默默地提供更好用的辅助能力。

拿日志功能来说，老项目可能还在用error_log()或者自己写的log_message()，功能单一，维护也麻烦。换成monolog/monolog，风险几乎为零：

• 安装简单：composer require monolog/monolog。
• 在配置初始化的地方创建实例：$logger = new \Monolog\Logger(‘main’);，再加个StreamHandler把日志输出到文件。
• 原有的旧代码，完全可以继续使用老的日志函数；而在新开发的模块、新接口里，统一使用$logger->info()。这样就形成了一种渐进式的覆盖。
• 后续想扩展功能也方便，加个SlackHandler推送到群聊，或者用ElasticsearchHandler做日志分析，都不需要去改动老逻辑。

类似的，像安全处理、HTTP客户端（比如guzzlehttp/guzzle）、配置加载（比如symfony/yaml）这些，都属于“无侵入”的第一梯队工具，可以根据项目需要，单点切入，逐步替换。

迁移过程中最易忽略的陷阱：include_path 和 __autoload 冲突

很多遗留系统，还依赖着set_include_path()或者自定义的__autoload()函数来加载类。Composer的vendor/autoload.php会注册自己的spl_autoload_register()。但如果旧的__autoload没有被显式注销或处理，在PHP 7.2+环境下会收到弃用警告，到了PHP 8+，可能就直接报致命错误了。

• 首先，检查一下入口文件或者公共配置文件里，有没有调用set_include_path()。如果有，建议先注释掉，或者至少把它移到Composer autoloader加载之后（不过有了Composer，它基本就没必要存在了）。
• 其次，全局搜索一下项目里有没有function __autoload。如果找到了，最好用spl_autoload_register(function ($class) { … })来替换它，并且确保这个注册只执行一次。
• 更稳妥的做法是：在引入vendor/autoload.php之后，立刻调用spl_autoload_unregister(‘__autoload’);（前提是你能确定旧的自动加载函数确实不再需要了）。
• 临时调试时有个小技巧：在关键位置加上var_dump(spl_autoload_functions());，可以打印出当前所有注册的自动加载器的顺序和内容，一目了然。

这一步如果没处理好，后续引入任何带命名空间的新包，都可能出现类加载混乱。错误表现会非常不稳定——有时候能加载成功，有时候又提示Class not found，排查半天才发现，原来是两个autoloader在抢着解析同一个类名。