ThinkPHP8.0MongoDB数据库_ThinkPHP8.0MongoDB连接使用【扩展】-ThinkPHP-PHP中文网

tp8连mongodb需三步：装php官方mongodb扩展、用composer require topthink/think-mongo、配置type='mongo'并设模型$connection和$collection。缺一即报class not found或查空。

thinkphp8.0mongodb数据库_thinkphp8.0mongodb连接使用【扩展】

TP8 连 MongoDB 不是改个配置就能用，必须装对扩展、配对驱动、写对模型——漏一步，Class 'think\mongo\Connection' 或 Class 'MongoDB\Client' 找不到就直接报错。

确认 PHP 环境已装官方 mongodb 扩展

TP8 本身不带 MongoDB 驱动，它依赖底层 PHP 的 mongodb 扩展（不是废弃的 mongo）。没这个扩展，任何 TP8 MongoDB 包都会失败。

运行 php -m | grep mongodb，有输出才表示扩展已加载
Windows 用户注意：必须下载与 PHP 版本、TS/NTS、VC 编译器完全匹配的 php_mongodb.dll，放进 ext/ 并在 php.ini 加 extension=mongodb
Mac/Linux 用 Homebrew 或 PECL 安装后，记得重启 PHP-FPM 或 Apache/Nginx，否则 phpinfo() 里也看不到
常见错误：Class 'MongoDB\Client' not found —— 八成是这步没走通，别急着配 TP8

用 composer require topthink/think-mongo 而非 mongodb/mongodb

TP8 要的是 ThinkPHP 官方适配层，不是 MongoDB 官方驱动包。装错包会导致模型无法识别连接类型或方法缺失。

mongodb-query

用于调试和故障排查，查询MongoDB数据库。用户需要时可以： (1) 列出所有数据库； (2) 列出数据库中的集合； (3) 执行MongoDB查询或命令。

下载

执行：composer require topthink/think-mongo（注意不是 mongodb/mongodb）
该包提供 \think\mongo\Connection 和 \think\mongo\Query，是 TP8 能识别的 MongoDB 封装
如果已误装 mongodb/mongodb，先 composer remove mongodb/mongodb 再重装 topthink/think-mongo
装完检查 vendor/topthink/think-mongo/src/Connection.php 是否存在，这是驱动入口

database.php 中 type 必须设为 'mongo'，且不能混用原生 Client

TP8 的数据库连接工厂靠 type 字段决定实例化哪个连接类。设成 'type' => 'mongo' 才会调用 think-mongo 提供的 Connection；设成其他值（比如 'type' => '\MongoDB\Client'）会直接跳过驱动层。

正确配置示例（config/database.php）：

return [
    'connections' => [
        'mongo' => [
            'type'     => 'mongo',
            'hostname' => '127.0.0.1',
            'hostport' => '27017',
            'database' => 'myapp',
            'username' => '',
            'password' => '',
            'options'  => ['connectTimeoutMS' => 5000],
        ],
    ],
];

不要在模型里手动 new MongoDB\Client 再塞进模型属性——这样绕过了 TP8 查询构造器和事件机制，where()、save() 等方法全失效
不要把 retryWrites=true 写进 hostname 字段，它属于连接 URI 参数，think-mongo 不解析这个；如需启用，得在 options 里传 ['retryWrites' => true]（仅限较新版本支持）

模型中必须声明 $connection = 'mongo' 且指定 $collection

TP8 不会自动把 Model 映射到 MongoDB，必须显式绑定连接名和集合名，否则默认走 MySQL 连接，查出来是空数组或报错。

模型代码示例（app/model/User.php）：

namespace app\model;
use think\Model;

class User extends Model
{
    protected $connection = 'mongo';
    protected $collection   = 'users'; // 注意：不是 table，是 collection
}

$collection 是必需的，TP8 的 think-mongo 驱动靠它定位文档集合；漏掉会查 user（默认表名）而不是你想要的 users
不要用 protected $table = 'users' —— MongoDB 没有 table 概念，这个字段会被忽略
查询时用 where() 没问题，但操作符要符合 MongoDB 语法，比如 where('age', '>', 18) 可用，但 whereRaw() 里的 JSON 字符串必须是 PHP 数组格式，不是 JSON 字符串