README

Mongo PHP 适配器是一个用户库，旨在作为依赖于ext-mongo的应用程序和新的驱动程序（ext-mongodb）之间的适配器。

它提供了基于mongo-php-library构建的ext-mongo API，因此与PHP 7兼容。

目标

这个库旨在为依赖于ext-mongo的库（例如Doctrine MongoDB ODM）但希望迁移到PHP 7（在PHP 7上ext-mongo无法运行）的应用程序提供兼容层。

如果你不依赖于使用ext-mongo的库，请不要使用此库。如果你正在开始一个新的项目，请查看mongodb/mongodb。

安装

此库要求您已安装mongodb扩展，并且它与旧的mongo扩展冲突。

安装此库的首选方法是使用Composer，在项目根目录下运行以下命令

$ composer config "platform.ext-mongo" "1.6.16" && composer require alcaeus/mongo-php-adapter

上述命令首先将mongo扩展标记为已安装，然后需要此适配器。这是为了解决composer中的一个bug，请参阅composer/composer#5030。

已知问题

返回值和异常

某些方法可能不会抛出与它们的ext-mongo对应者相同的异常消息。不要依赖异常消息相同。

返回包含connectionId字段的结果数组的方法将始终返回0作为连接ID。

错误

由ext-mongo触发的所有错误和警告都作为E_USER_WARNING和E_USER_ERROR触发，因为trigger_error不接受E_WARNING和E_USER代码。如果您在错误处理例程中依赖于这些错误代码，请相应地更新您的代码。

对象的序列化

任何Mongo*对象（例如MongoGridFSFile、MongoCursor等）的序列化将不会正常工作。对象可以被序列化，但在反序列化后无法使用。

Mongo

• Mongo类已弃用，并且在此库中没有实现。如果您仍在使用它，请更新您的代码以使用新的类。

MongoLog

• MongoLog类不会记录任何内容，因为底层驱动程序不提供检索此数据的方法。

MongoClient

• connect和close方法尚未实现，因为底层驱动程序是懒连接的，并且不提供连接和断开连接的方法。
• getConnections方法尚未实现，因为底层驱动程序不提供检索此数据的方法。
• killCursor方法尚未实现。

MongoDB

• authenticate方法不受支持。要使用认证连接到数据库，请使用连接字符串提供凭据。
• 由于底层驱动程序的问题，无法使用$cmd集合。要运行命令，请使用command方法，而不是查询虚拟的$cmd集合。

MongoCollection

• insert、batchInsert和save方法通过引用接收第一个参数。虽然原始API没有明确指定引用参数，但它确实向提供的对象和文档中添加了一个ID字段。
• parallelCollectionScan方法尚未实现。

MongoCursor

• info方法无法可靠地填写游标信息中的所有字段。这包括numReturned和server键，一旦游标开始迭代。numReturned字段将始终显示与at字段相同的值。server字段缺少认证信息。
• setFlag方法尚未实现。
• timeout方法不会更改任何查询选项。新驱动程序不再支持客户端超时。使用maxTimeMS设置作为替代。

MongoCommandCursor

• createFromDocument方法尚未实现。
• info方法无法可靠地填写游标信息中的所有字段。这包括at、numReturned、firstBatchAt和firstBatchNumReturned字段。at和numReturned字段始终返回0，以与MongoCursor保持兼容。firstBatchAt和firstBatchNumReturned字段将包含相同的值，即迭代器的内部位置。

开发

如果您正在为此驱动程序开发补丁，您可以从repo目录的根目录按照以下步骤运行单元测试

$ composer install
$ vendor/phpunit/phpunit/phpunit --verbose

它假定localhost正在运行mongod服务器。以下是启动mongod以进行这些测试的示例命令

$ mongod --smallfiles --fork --logpath /var/log/mongod.log --setParameter enableTestCommands=1

测试还假定PHP 5.6+和ext-mongodb扩展可用。