/ /

连接选项

Overview

在本指南中，您可以了解连接、身份验证和驱动程序选项，以及如何在 Laravel 应用程序的数据库连接配置中指定这些选项。连接选项将传递到 MongoDB PHP 库，该库管理数据库连接。

要学习；了解有关MongoDB PHP库的更多信息，请参阅MongoDB PHP库文档。

本指南涵盖以下主题：

连接和身份验证选项
驱动程序连接选项
禁用ID字段名称转换

连接和身份验证选项

通过以下部分，了解如何将常用连接和身份验证选项添加到配置文件中：

添加连接和身份验证选项
选项说明

添加连接和身份验证选项

您可以使用以下方法之一在 Laravel Web 应用程序的config/database.php配置文件中指定连接或身份验证选项：

将设置和值作为数组项添加到options数组项中。
将设置和值作为查询string参数附加到 dsn 数组项中指定的连接string上。

要在options数组中指定选项，请将其名称和值添加为数组项，如下例所示：

'connections' => [
    'mongodb' => [
        'dsn' => 'mongodb+srv://mongodb0.example.com/',
        'driver' => 'mongodb',
        'database' => 'sample_mflix',
        'options' => [
            'appName' => 'myLaravelApp',
            'compressors' => 'zlib',
            'zlibCompressionLevel' => 7,
        ],
    ],
],

要将选项指定为连接string中的参数，请使用以下查询string语法格式：

添加问号字符? ，以将主机信息与参数分隔开。
通过将选项的格式设置为<option>=<value>来添加选项。
在每个选项和值对之间插入与符号&进行分隔。

以下设置示例显示了连接string参数语法：

'dsn' => 'mongodb+srv://mongodb0.example.com/?appName=myLaravelApp&compressors=zlib',

选项说明

下表描述了连接和身份验证选项及其默认值的列表：

选项名称	接受的值	默认值	说明
appName	字符串	无	指定 MongoDB PHP 库作为握手的一部分发送给 MongoDB 部署的应用程序名称。指定 `appName` 可帮助您在服务器日志中识别与该应用程序相关的活动。
authMechanism	字符串	无	指定要使用的身份验证机制。如果不指定此选项，驱动程序将使用默认的身份验证机制。要了解更多信息，请参阅 MongoDB Server手册中的身份验证。
authMechanismProperties	字符串	无	指定更多与`authMechanism`选项中设置的身份验证机制相关的属性。
authSource	字符串	查看说明	指定用于身份验证的数据库。对于基于 SCRAM 的身份验证机制，此选项默认为 `admin`；对于 `MONGODB-X509` 机制，此选项默认为 `$external`；对于 `PLAIN` 机制，此选项默认为数据库名称或 `$external`。
compressors	以逗号分隔的字符串列表	无	指定 MongoDB PHP 库用于按指定顺序减少 MongoDB 与应用程序之间传递的网络数据量的数据压缩器。
connectTimeoutMS	Non-negative integer	`10000` （10 秒）	指定尝试连接到服务器时传递给每个底层 TCP 流的连接超时时间（以毫秒为单位）。
directConnection	布尔	`false`	指定是否直接连接到单个主机，而不是发现并连接到集群中的所有服务器。要了解有关此设置的更多信息，请参阅连接指南中的直接连接。
heartbeatFrequencyMS	整数大于或等于 `500`	`10000` （10 秒）	指定每个监控线程在执行服务器检查之间的等待时间（以毫秒为单位）。
journal	布尔	`false`	请求确认操作已传播到磁盘上日志。
localThresholdMS	Non-negative integer	`15`	指定驱动程序与服务器之间的平均往返时间可以持续的毫秒数，与所有适合服务器的最短往返时间相比。 `0` 的值表示没有延迟窗口，因此，只有平均往返时间最短的服务器才符合条件。
maxStalenessSeconds	`-1`，或任何大于或等于的整数 `90`	`-1`	指定从主节点开始的最大延迟时间（以秒为单位），在此时间内，可以将从节点(secondary node from replica set)视为可用于给定操作。此选项的值必须至少为 `90`，否则操作会出错。`-1` 表示没有最大延迟。
maxTimeMS	Non-negative integer	无	指定一个默认时间限制，以毫秒为单位，适用于项目级别的所有查询。您可以对单个查询进行此配置的覆盖。
readConcernLevel	字符串	无	Specifies the default read concern for operations performed by the MongoDB PHP Library. To learn more, see Read Concern in the Server manual.
readPreference	字符串	`primary`	指定 MongoDB PHP 库如何将读取操作路由到副本集成员。要了解更多信息，请参阅 MongoDB Server手册中的读取偏好。
readPreferenceTags	以逗号分隔的键值对列表	无	指定考虑对哪些副本集成员进行操作。此键的每个实例都是一个单独的标签集。驱动程序会检查每个标签集，直到找到带有每个标签的一个或多个服务器。
replicaSet	字符串	无	指定 MongoDB PHP 库连接到的副本集的名称。
retryReads	布尔	`true`	指定 MongoDB PHP 库在操作失败时是否重试读取操作。
serverSelectionTimeoutMS	Non-negative integer	`30000` （30 秒）	指定 MongoDB PHP 库在超时之前等待为操作选择服务器的时间（以毫秒为单位）。
TLS	布尔	`false`	指定 MongoDB PHP 库在与服务器的连接中使用的 TLS 配置。默认情况下，TLS 处于关闭状态。
tlsAllowInvalidCertificates	布尔	`false`	指定如果服务器提供无效证书，MongoDB PHP 库是否返回错误。我们建议仅在测试环境中将此选项设置为 `true`，以避免在应用程序中创建安全漏洞。
tlsCAFile	字符串	查看说明	指定 MongoDB PHP 库用于 TLS 的证书权威 (CA) 文件的路径。如果您未指定此选项，驱动程序将使用 `webpki-roots` crate 中的 Mozilla 根证书。
tlsCertificateKeyFile	字符串	无	指定 MongoDB PHP 库向服务器呈现的证书文件的路径，以验证其身份。如果您未设置此选项，MongoDB PHP 库将不会尝试向服务器验证其身份。
tlsInsecure	布尔	`false`	指定如果服务器提供无效证书，MongoDB PHP 库是否返回错误。我们建议仅在测试环境中将此选项设置为 `true`，以避免在应用程序中创建安全漏洞。
w	非负整数或字符串	无	Requests acknowledgment that the operation has propagated to a specific number or variety of servers. To learn more, see Write Concern in the Server manual.
wtimeoutMS	Non-negative integer	无超时	指定写关注的时间限制（以毫秒为单位）。如果操作未在时限内传播到请求的级别，MongoDB PHP 库将引发错误。
zlibCompressionLevel	介于 `-1` 和 `9`（含）之间的整数	`-1`	指定使用 `zlib` 压缩器时的压缩的级别字段。将值设置为 `-1` 可选择默认压缩级别 (`6`)。将值设置为 `0` 表示无压缩，将值设置为 `9` 表示最大压缩。

To see a full list of connection options, see the Connection String Options section of the Connection Strings guide in the Server manual. Select PHP from the Select your language dropdown menu on the right side of the page.

驱动程序连接选项

驱动程序选项修改 MongoDB PHP 库的行为，该库管理 Laravel 应用程序和 MongoDB 之间的连接和所有操作。

您可以在 Laravel Web 应用程序的config/database.php配置文件中指定驱动程序选项。要添加驱动程序选项，请将设置和值作为数组项添加到driver_options数组项中，如下例所示：

'connections' => [
    'mongodb' => [
        'dsn' => 'mongodb+srv://mongodb0.example.com/',
        'driver' => 'mongodb',
        'database' => 'sample_mflix',
        'driver_options' => [
            'serverApi' => 1,
            'allow_invalid_hostname' => false,
        ],
    ],
]

有关驱动程序选项列表，请参阅 MongoDB PHP 库文档的$driverOptions: array部分。

禁用ID字段名称转换

从 Laravel MongoDB v5.0 开始，id 是MongoDB文档中 _id字段的别名，在查询和存储数据时，该库会自动将顶级字段和嵌入式字段的 id 转换为 _id。

使用 Laravel MongoDB v5.3 或更高版本时，您可以为嵌入式文档禁用从 id 自动转换为 _id 的功能。为此，请执行以下任一操作：

在 config/database.php文件中将 rename_embedded_id_field 设置为 false：

'connections' => [
    'mongodb' => [
        'dsn' => 'mongodb+srv://mongodb0.example.com/',
        'driver' => 'mongodb',
        'database' => 'sample_mflix',
        'rename_embedded_id_field' => false,
        // Other settings
    ],
],

将 false 传递给应用程序中的 setRenameEmbeddedIdField() 方法：
DB::connection('mongodb')->setRenameEmbeddedIdField(false);

重要

我们建议仅使用此选项来提供与现有文档模式的向后兼容性。在新项目中，避免在嵌入式文档中使用 id 作为字段名称，这样可以保持 Laravel MongoDB 的默认行为。