phpEnv是一款面向Windows平台的PHP集成环境工具，它将Apache、Nginx、MySQL、PHP等组件打包管理，方便开发者在本地快速搭建Web项目。当项目需要使用MongoDB这类NoSQL数据库时，默认安装的PHP并不包含MongoDB扩展，因此需要手动安装并配置对应的扩展文件。本文将以phpEnv环境为例，详细介绍从扩展下载、配置到连接测试的完整过程。
一、phpEnv环境准备与MongoDB扩展安装
在开始安装之前，首先要确认phpEnv中当前使用的PHP版本。不同PHP版本对应不同的MongoDB扩展编译版本，版本不匹配是导致扩展无法加载的主要原因之一。打开phpEnv主界面，查看当前启用的PHP版本号，例如PHP 7.4或PHP 8.0。记住这个版本号，后续下载扩展时需要严格对应。
MongoDB官方提供了Windows平台下预编译的DLL扩展文件，通常可以在PECL仓库或MongoDB官方驱动下载页面找到。下载时需要注意三个匹配条件：PHP主版本号、线程安全类型（TS或NTS）以及操作系统位数（x86或x64）。phpEnv默认集成的是线程安全版本（TS）的PHP，所以应当选择带TS标识的扩展包。下载完成后解压，找到php_mongodb.dll文件，将其复制到phpEnv安装目录下的对应PHP版本ext目录中，例如C:\phpEnv\php\php-7.4\ext。
这里需要特别说明：不要使用老旧的php_mongo.dll扩展。php_mongo.dll对应的是已经停止维护的mongo扩展，新版本的PHP环境无法使用。官方推荐的扩展名称是php_mongodb.dll，对应扩展名为mongodb。安装成功后PHP代码中使用的命名空间是MongoDB\Driver，而不是Mongo。
二、配置php.ini并验证扩展加载
复制DLL文件后，需要修改当前PHP版本对应的php.ini配置文件。在phpEnv中，每个PHP版本都有独立的php.ini文件，通常位于ext目录的上级目录中，例如C:\phpEnv\php\php-7.4\php.ini。使用文本编辑器打开该文件，在扩展配置区域添加一行配置：
extension=php_mongodb.dll
保存php.ini后，需要重启phpEnv中的Apache或Nginx服务，使新的配置生效。重启完成后，可以通过两种方式验证扩展是否成功加载。第一种是在phpEnv的PHP设置中查看已加载扩展列表；第二种是执行命令行命令php -m，在输出的扩展列表中查找mongodb。如果能看到mongodb，说明扩展已经正确加载，可以进入下一步连接测试。
如果命令行中找不到php命令，可以切换到phpEnv的PHP安装目录，例如C:\phpEnv\php\php-7.4，在该目录下执行php -m。另外，也可以创建一个phpinfo文件，在Web根目录下放置一个包含<?php phpinfo(); ?>的文件，通过浏览器访问该文件，在页面中搜索mongodb。找到对应配置段落即表示扩展已生效。
三、使用PHP连接MongoDB数据库
扩展安装完成之后，就可以在PHP代码中通过MongoDB\Driver\Manager类连接到MongoDB数据库。该类是mongodb扩展提供的核心入口类，负责管理与数据库服务器的连接。连接时需要指定MongoDB的连接字符串，常见格式为mongodb://用户名:密码@服务器地址:端口号。如果数据库没有开启认证，可以直接使用mongodb://127.0.0.1:27017。
下面是一个完整的连接测试示例，通过构造Manager对象并执行ping命令来确认连接是否成功：
<?php
// 引入自动加载（如果使用Composer）
require_once 'vendor/autoload.php';
// 创建MongoDB连接管理器
$manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1:27017');
// 构造ping命令
$command = new MongoDB\Driver\Command(['ping' => 1]);
try {
// 执行命令
$cursor = $manager->executeCommand('admin', $command);
$response = $cursor->toArray()[0];
echo "MongoDB连接成功，响应：" . json_encode($response) . PHP_EOL;
} catch (MongoDB\Driver\Exception\Exception $e) {
echo "连接失败：" . $e->getMessage() . PHP_EOL;
}
?>
在上面的代码中，executeCommand方法用于向指定的数据库发送命令。admin数据库是MongoDB的管理数据库，ping命令通常可以在任意数据库下执行，但习惯上使用admin。如果连接成功，toArray方法会返回一个包含响应文档的数组，输出结果中ok字段的值为1。如果连接失败，例如MongoDB服务未启动或端口被防火墙拦截，会抛出异常，通过捕获异常可以获取具体的错误信息。
如果MongoDB开启了用户认证，连接字符串需要包含用户名和密码，例如：
$manager = new MongoDB\Driver\Manager('mongodb://admin:123456@127.0.0.1:27017/admin');
连接字符串末尾的/admin表示认证数据库，需要根据实际配置修改。如果密码包含特殊字符，建议使用parse_url函数或直接对密码进行URL编码，避免连接字符串解析错误。另外，MongoDB\Driver\Manager还支持连接选项数组，例如设置连接超时时间：
$options = [
'connectTimeoutMS' => 3000,
'socketTimeoutMS' => 5000,
];
$manager = new MongoDB\Driver\Manager('mongodb://127.0.0.1:27017', [], $options);
四、常见问题排查与优化建议
在phpEnv中配置MongoDB扩展时，最常见的问题是扩展无法加载。如果php -m中看不到mongodb，可以从以下几个方面排查：第一，确认php_mongodb.dll文件是否放入了当前PHP版本的ext目录；第二，确认php.ini中extension配置是否写错，注意扩展名是php_mongodb.dll而不是php_mongo.dll；第三，确认下载的DLL文件是否与当前PHP版本匹配，包括TS/NTS和位数。任何一个条件不满足都会导致加载失败。
另一个常见问题是连接MongoDB时出现认证失败错误。这通常是因为连接字符串中的用户名、密码或认证数据库不正确。可以在MongoDB shell中使用db.auth()命令验证账号信息，或者查看MongoDB日志文件。如果是本机测试环境，可以暂时关闭认证，确认连接代码本身没有问题后再开启认证。
对于连接超时问题，建议检查MongoDB服务是否启动，Windows下可以在服务管理器中查看MongoDB Server服务状态。同时检查防火墙是否放行27017端口。如果MongoDB运行在虚拟机或远程服务器上，需要将连接字符串中的127.0.0.1替换为实际服务器IP地址，并确保远程访问配置已经开启。MongoDB默认只监听127.0.0.1，需要修改mongod.cfg文件中的bindIp配置为0.0.0.0才能允许远程连接。
配置完成后，建议在项目中使用Composer安装mongodb/mongodb库，该库提供了更高层的API封装，能够简化增删改查操作。底层驱动仍然依赖php_mongodb.dll扩展。合理设置连接池和超时参数也能提升程序稳定性。phpEnv的图形界面可以方便地切换PHP版本，但切换版本后需要重新为对应版本配置扩展，这一点在多版本开发时尤其需要注意。