/ /

连接指南

Overview

在本指南中，您可以了解如何使用 Laravel MongoDB 将 Laravel 应用程序连接到 MongoDB 实例或副本集部署。

本指南包括以下部分：

Connection URI, which explains connection URIs and their constituent parts
Laravel Database Connection Configuration, which explains how to set up your MongoDB database connection for your Laravel app.
Connection Example, which provides examples that show how to connect to MongoDB by using an Atlas connection string.
连接到 MongoDB 的其他方式描述了连接到非 Atlas 托管的 MongoDB 部署的方法。

连接 URI

连接 URI （也称为连接string ）指定 Laravel 集成如何连接到MongoDB以及连接时的行为方式。

一个连接 URI 的组成部分

连接字符串包括以下组件：

组件	说明
`mongodb://` or `mongodb+srv://`	Required. A prefix that identifies the URI as a string in the standard connection format (`mongodb://`) or in the SRV connection format (`mongodb+srv://`). For more information, see Connection String Formats.
`username:password`	可选。使用 `<username>:<password>` 格式指定用于身份验证的数据库用户名和密码。如果您的部署不需要身份验证，请忽略此部分。
`host[:port]`	必需。运行 MongoDB 的主机和可选端口号。如果不包含端口号，驱动程序将使用默认端口`27017` 。请注意，仅在使用标准连接格式时支持指定端口号。如果使用SRV 连接格式，请省略端口号。
`/defaultauthdb`	可选。如果连接string包含 `username:password@` 身份验证档案但不包含 `authSource` 选项，则要使用的身份验证数据库。如果不包含此组件，客户端将根据`admin`数据库对用户进行身份验证。 Can also be the application database if and only if the `database` option is not specified in the database configuration array.
`?<options>`	可选。一个查询字符串，它将特定于连接的选项指定为 `<name>=<value>` 对。有关这些选项的完整说明，请参阅连接选项指南。

以下示例显示了一个完整的连接 URI，其中指定了协议、凭证、主机名和端口以及连接选项：

mongodb://myUser:myPass123@localhost:27017/?w=majority&retryWrites=true

For more information on connection strings, see Connection Strings in the Server manual manual.

Laravel 数据库连接配置

Laravel 集成允许您在config/database.php Laravel应用程序文件中配置MongoDB 数据库连接。您可以在此文件中指定以下连接详细信息：

default，指定在以下情况下要使用的数据库连接：未指定
connections，其中包含用于从应用程序访问一个或多个数据库的数据库连接信息

您可以使用配置文件中的以下代码将默认连接设置为connections数组中相应的mongodb条目：

'default' => 'mongodb',

对于MongoDB database连接，您可以指定以下详细信息：

设置

说明

driver

指定用于连接的数据库驱动程序。

dsn

指定 MongoDB 连接 URI 的数据源名称 (DSN)。

host

指定部署中一个或多个 MongoDB 节点的网络地址和端口。您可以使用此设置代替 dsn 设置。
要指定单个主机，请将主机名和端口作为 string 传递，如以下示例所示：

'host' => 'myhost.example.com:27017',

要指定多个主机，请将它们传递到数组中，如以下示例所示：

'host' => ['node1.example.com:27017', 'node2.example.com:27017', 'node3.example.com:27017'],

注意

此选项不接受使用 DNS 种子列表连接格式的主机。

database

指定要读取和写入的MongoDB database的名称。

username

指定数据库用户的用户名凭证，以便与 MongoDB 进行身份验证。

password

指定数据库用户的密码档案，以便与 MongoDB 进行身份验证。

options

指定要传递给 MongoDB 以确定连接行为的连接选项。要了解有关连接选项的更多信息，请参阅连接和身份验证选项。

driver_options

指定特定于传递给 MongoDB PHP 库的选项，该库确定该连接的驱动程序行为。要了解有关驱动程序选项的更多信息，请参阅驱动程序连接选项。

注意

您可以将 dsn 配置中的以下设置指定为MongoDB连接string中的参数，而不是数组项：

host
username
password
options 和driver_options ，由选项名称指定

重要

Laravel 集成不支持prefix 和 prefix_indexes 连接设置。

以下示例显示如何在connections数组项中指定 MongoDB 连接详细信息：

示例 config/database.php MongoDB 连接配置

'connections' => [
    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => 'mongodb+srv//myUser:myPass123@sample.host/',
        'database' => 'sample_mflix',
        'options' => [
            'w' => 'majority',
        ],
        'driver_options' => [
            'serverApi' => 1,
        ],
    ],
    // ...
],

以下部分提供了指定 MongoDB 连接的常用方法。

连接示例

本部分介绍如何使用MongoDB Atlas连接string配置 Laravel 应用程序的 DSN。

要将 MongoDB DSN 添加到 Laravel 应用程序，请进行以下更改：

将 DSN 作为环境变量添加到项目的.env环境配置文件中。将变量值设置为Atlas连接string 。
在config/database.php配置文件的connections数组中为 MongoDB 连接添加一个连接条目。将连接条目的dsn值设置为引用包含 DSN 的环境变量。

以下示例展示如何在相关配置文件中将 "mongodb+srv://myUser:myPass123@mongodb0.example.com/" 指定为连接string ：

示例 .env 环境配置

DB_URI="mongodb+srv://myUser:myPass123@mongodb0.example.com/"

示例 config/database.php 连接条目

'connections' => [
    'mongodb' => [
        'dsn' => env('DB_URI'), // uses the value of the DB_URI environment variable
        'driver' => 'mongodb',
        'database' => 'sample_mflix',
        // ...
    ],
  // ...
]

提示

要检索Atlas连接string ，请按照快速入门教程的创建连接string步骤进行操作。

连接 MongoDB 的其他方式

以下部分向您展示如何连接到单个 MongoDB Server 实例或未托管在 MongoDB Atlas 上的副本集。

连接到本地计算机上的 MongoDB Server

本部分展示了从同一台计算机（例如本地开发环境）运行string Laravel 应用程序和MongoDB 服务器时可以使用的示例连接。

要将应用程序连接到同一计算机上托管的 MongoDB 实例，您必须完成以下任务：

下载、安装并运行 MongoDB 服务器。
获取运行 MongoDB Server 的 IP 地址和端口。如果使用本地安装的 MongoDB 服务器的默认设置，则 IP 地址为127.0.0.1 ，端口为27017 。
设置config/database.php连接以引用环境变量DB_URI作为dsn的值，如连接示例部分所示。

以下示例显示了一个示例连接string .env，如果您的应用程序连接到在默认MongoDB IP地址和端口上运行的 Server，则可以将其添加到文件中：

示例 .env 环境配置以连接到本地 MongoDB 服务器。

DB_URI="mongodb://127.0.0.1:27017/";

To learn how to download and install MongoDB server, see Install MongoDB Community Edition in the Server manual.

连接到副本集

MongoDB 副本集部署是一组连接的实例或节点，其中的节点存储相同的数据集。这种实例配置提供了数据冗余和高数据可用性。

要连接到副本集部署，请指定每个节点的主机名和端口号（以逗号分隔），并将副本集名称指定为连接string中 replicaSet 参数的值。

此示例显示了可以添加到 Laravel 应用程序的 .env 文件以连接到副本集的连接string ，该示例使用以下示例值：

host1、 host2和host3作为 MongoDB 节点的主机名
27017 作为 MongoDB 在这些主机上运行的端口
myRS 作为副本集的配置名称
myUser 和myPass123作为数据库用户的档案

DB_URI="mongodb://myUser:myPass123@host1:27017,host2:27017,host3:27017/?replicaSet=myRS"

连接到副本集时，除非另有说明，否则 Laravel 集成用于管理与MongoDB的连接的库会执行以下操作：

在给定任一节点的地址时发现所有副本集节点。
向相应成员发送操作，例如针对主节点进行写入的指令。要了解有关副本集主节点的更多信息，请参阅 MongoDB Server手册中的副本集主节点。

提示

您只需指定一台主机即可连接到副本集。但是，为了在所选主机不可用时确保连接，请提供完整的主机列表。

要了解有关设置MongoDB 副本集的更多信息，请参阅 MongoDB Server手册中的部署副本集。

DirectConnection

要强制操作在MongoDB副本集中的特定节点上运行，请在连接string和具有 true 值的 directConnection 参数中指定该节点的连接信息。

直接连接有以下限制：

无法使用 DNS 种子列表连接格式连接字符串。
当指定主机不是主节点时，写入操作会失败。
When the host is not the primary, you must specify the secondary read preference in your connection options. To learn more about this limitation, see the secondary read preference entry in the Server manual.

以下示例显示了可以添加到 Laravel 应用程序的 .env 文件中的连接string ，以建立与MongoDB副本集中从节点的直接连接。该示例使用以下样本值：

host2 作为从节点的主机名
27017 作为 MongoDB 节点侦听的端口

示例 .env 环境配置以启用直接连接

DB_URI="mongodb://host2:27017/?directConnection=true&readPreference=secondary"