/ /

连接选项

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$external` ；对于`MONGODB-X509` 机制，此选项默认为数据库名称或`$external` `PLAIN`。
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)节点可考虑用于给定操作的主节点 (primary node in the replica set)节点之后的最大延迟（以秒为单位）。此选项的值必须至少为 `90`，否则操作会引发错误。值为`-1` 表示没有最大延迟。
readConcernLevel	字符串	无	指定 MongoDB PHP 库执行的操作的默认读关注。要了解更多信息，请参阅 MongoDB Server手册中的读关注。
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	非负整数或字符串	无	请求确认操作已传播到特定数量或种类的服务器。要学习；了解更多信息，请参阅服务器手册中的写关注。
wtimeoutMS	Non-negative integer	无超时	指定写关注的时间限制（以毫秒为单位）。如果操作未在时限内传播到请求的级别，MongoDB PHP 库将引发错误。
zlibCompressionLevel	介于 `-1` 和 `9`（含）之间的整数	`-1`	`zlib`如果使用压缩器，请指定该压缩器的压缩级别字段。将值设置为 `-1`将选择默认压缩级别`6` ()。将值设置为 `0`指定不压缩，将值设置为`9` 指定最大压缩。

要查看连接选项的完整列表，请参阅 stringMongoDB Server手册中连接字符串指南的连接选项部分。从页面右侧的Select your language下拉菜单中选择PHP 。

驱动程序连接选项

驱动程序选项修改 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 的默认行为。

后退

连接指南

来年

TLS 配置