常见问题解答

常见扩展安装错误

/private/tmp/pear/install/mongodb/php_phongo.c:24:10: fatal error: 'php.h' file not found
#include <php.h>
         ^~~~~~~

php vendor/mongodb/mongodb/tools/detect-extension.php

<pre><?php require(...); ?></pre>

PHP Warning:  PHP Startup: Unable to load dynamic library 'mongodb'

连接处理和持久性

连接到MongoDB部署由libmongoc库和PHP扩展处理。当你构建一个MongoDB\Client 实例，PHP 库通过相同的连接字符串和选项创建了一个 MongoDB\Driver\Manager 实例。该扩展也使用这些构造函数参数来推导持久 libmongoc 客户端的哈希键。如果您之前使用密钥持久化了一个 libmongoc 客户端，则它将被重用。否则，将创建一个新的 libmongoc 客户端，并在 PHP 工作进程的生命周期内进行持久化。您可以在 PHP 扩展文档

每个 libmongoc 客户端都维护自己的连接到 MongoDB 部署及其拓扑视图。当您重用持久 libmongoc 客户端时，PHP 库可以避免建立新连接和重新发现拓扑的开销。这种方法通常可以提高性能，并且是驱动程序的默认行为。

持久 libmongoc 客户端将在 PHP 工作进程结束时才被释放。这意味着在 MongoDB\Driver\Manager 对象超出作用域后，连接到 MongoDB 部署可能会保持打开状态。虽然这通常不是连接到一个 MongoDB 部署的应用程序的问题，但在某些情况下可能会出现问题，以下列表中进行了描述

• PHP-FPM 配置了 pm.max_requests=0，因此工作进程永远不会重启，并且 PHP 应用程序被多次部署，对其 MongoDB 连接字符串或选项进行了微小更改。这可能导致每个工作进程中的 libmongoc 客户端对象累积。

• 应用程序偶尔会连接到后端组件中的单独 MongoDB 部署，其中请求延迟不是最重要的方面。

在第一种情况下，作为应用程序部署的一部分重启 PHP-FPM 允许应用程序释放任何未使用的 libmongoc 客户端，并仍然使用持久客户端进行最新的连接字符串。

第二种情况需要不同的解决方案。将 disableClientPersistence 驱动程序选项指定为 true 指示 PHP 库创建一个新的 libmongoc 客户端，并确保在相应的 MongoDB\Driver\Manager 离开作用域时释放它。

以下代码演示了如何在创建客户端时将 disableClientPersistence 选项设置为 true

<?php
$client = new MongoDB\Client(
    uri: getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/',
    uriOptions: [],
    driverOptions: ['disableClientPersistence' => true],
);

在使用 disableClientPersistence 驱动程序选项之前请仔细考虑，因为放弃客户端持久性需要更多时间来建立与 MongoDB 部署的连接并发现其拓扑。

服务器选择失败

以下都是 服务器选择 失败的示例

No suitable servers found (`serverSelectionTryOnce` set):
  [connection refused calling hello on 'a.example.com:27017']
  [connection refused calling hello on 'b.example.com:27017']
No suitable servers found: `serverSelectionTimeoutMS` expired:
  [socket timeout calling hello on 'example.com:27017']
No suitable servers found: `serverSelectionTimeoutMS` expired:
  [connection timeout calling hello on 'a.example.com:27017']
  [connection timeout calling hello on 'b.example.com:27017']
  [TLS handshake failed: -9806 calling hello on 'c.example.com:27017']
No suitable servers found: `serverselectiontimeoutms` timed out:
 [TLS handshake failed: certificate verify failed (64): IP address mismatch calling hello on 'a.example.com:27017']
 [TLS handshake failed: certificate verify failed (64): IP address mismatch calling hello on 'b.example.com:27017']

这些错误通常表现为扩展的 MongoDB\Driver\Exception\ConnectionTimeoutException 异常。实际的异常消息来自 libmongoc，这是扩展使用的底层系统库。由于这些消息可以有多种形式，因此分解消息结构以更好地诊断应用程序中的错误是有帮助的。

消息通常以 "未找到合适的服务器" 开头。消息的下一部分表明了服务器选择失败的原因。默认情况下，扩展程序会避免服务器选择循环，而是根据 serverSelectionTryOnce 连接字符串选项进行单次尝试。如果扩展程序配置为使用循环，则类似于 "serverSelectionTimeoutMS 已过期" 的消息将告诉我们我们已经用完了其时间限制。

消息的最后部分告诉我们服务器选择失败的原因，并包括来自拓扑扫描器的直接错误，拓扑扫描器是负责连接和监控每个主机的服务。任何在监控期间最后发生错误的宿主都将包括在这个列表中。这些消息通常来自低级别的套接字或 TLS 函数。

以下内容并非旨在详尽无遗，但希望能帮助您找到分析服务器选择失败原因的方向

• "连接被拒绝" 可能表明远程主机未在预期的端口上监听。

• "连接超时" 可能表明存在路由或防火墙问题，或者可能是由于延迟导致的超时。

• "套接字超时" 暗示某个时候已建立连接，但由于延迟而断开或超时。

• "TLS 握手失败" 暗示与 TLS 或 OCSP 验证相关的问题，有时可能是 TLS 证书配置错误。

在连接失败的情况下，您可以使用 connect 工具尝试获取更多信息。此工具尝试使用套接字函数连接到连接字符串中的每个主机，以查看它是否能够建立连接、发送和接收数据。工具将连接字符串作为其唯一参数传递给 MongoDB 部署。假设您已通过 Composer 安装了库，您将从一个供应商目录调用脚本

php vendor/mongodb/mongodb/tools/connect.php mongodb://127.0.0.1:27017

如果服务器不接受连接，输出将类似于以下内容

Looking up MongoDB at mongodb://127.0.0.1:27017
Found 1 host(s) in the URI. Will attempt to connect to each.
Could not connect to 127.0.0.1:27017: Connection refused