文档菜单
文档首页
/
语言
/
PHP
/
Laravel MongoDB
/
基础
/
连接

连接指南

本页内容

  • 概述
  • 连接URI
  • 连接URI的组成部分
  • Laravel数据库连接配置
  • 连接示例
  • 其他连接到MongoDB的方法
  • 在本地机器上连接到MongoDB服务器
  • 连接到副本集

概述

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

本指南包括以下部分

  • 连接URI，解释了连接URI及其组成部分

  • Laravel 数据库连接配置 ，解释了如何为您的 Laravel 应用设置 MongoDB 数据库连接。

  • 连接示例 ，提供了通过使用 Atlas 连接字符串连接到 MongoDB 的示例。

  • 其他连接 MongoDB 的方式 描述了连接到非 Atlas 托管的 MongoDB 部署的方法。

连接 URI

一个 连接 URI，也称为连接字符串，指定了 Laravel 集成如何连接到 MongoDB 以及连接时的行为。

连接 URI 的组成部分

以下图表解释了示例连接 URI 的每个部分

Parts of a connection URI

在此连接 URI 中，mongodb+srv 是协议，它使用 DNS Seed List 连接格式，在您的部署中提供更大的灵活性，并能够在不重新配置客户端的情况下更改服务器。

如果托管您的 MongoDB 部署的机器不支持此功能，则使用 标准连接字符串格式 的协议。

如果您使用基于密码的认证，则连接字符串协议部分之后包含您的用户名和密码。将 user 的占位符替换为您的用户名，将 pass 替换为您的密码。如果您使用不需要用户名和密码的认证机制，则省略此连接 URI 的这部分。

连接字符串认证部分之后指定了您的 MongoDB 实例的主机名或 IP 地址和端口号。前面的示例使用 sample.host 作为主机名，27017 作为端口号。将这些值替换为指向您的 MongoDB 实例。

连接字符串的最后部分指定了连接和认证选项。在示例中，我们设置了以下连接选项和值

  • maxPoolSize=20

  • w=majority

要了解更多关于连接选项的信息，请参阅连接选项.

Laravel 数据库连接配置

Laravel 集成允许你在 Laravel 应用的 config/database.php 文件中配置 MongoDB 数据库连接。你可以在该文件中指定以下连接详情

  • default，指定在未指定时使用的数据库连接

  • connections，包含用于从应用访问一个或多个数据库的数据库连接信息

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

'default' => 'mongodb',

对于 MongoDB 数据库连接，你可以指定以下详情

设置
描述
driver
指定用于连接的数据库驱动。
dsn
数据源名称（DSN），它指定 MongoDB 连接 URI。
host
指定部署中的一个或多个 MongoDB 节点的网络地址和端口。您可以使用此设置而不是 dsn 设置。
要指定单个主机，将主机名和端口号作为字符串传递，如下例所示
'host' => 'myhost.example.com:27017',
要指定多个主机，将它们作为数组传递，如下例所示：
'host' => ['node1.example.com:27017', 'node2.example.com:27017', 'node3.example.com:27017'],
此选项不接受使用 DNS 种子列表连接格式的宿主机。
database
指定要读取和写入的 MongoDB 数据库名。
username
指定用于与 MongoDB 认证的数据库用户的用户名凭据。
password
指定用于与 MongoDB 认证的数据库用户的密码凭据。
options
指定传递给 MongoDB 的连接选项，这些选项确定连接行为。要了解更多关于连接选项的信息，请参阅 连接和认证选项。
driver_options
指定传递给 MongoDB PHP 库的特定选项，这些选项确定连接的驱动程序行为。要了解更多关于驱动程序选项的信息，请参阅 驱动程序连接选项。

注意

您可以在MongoDB连接字符串中指定以下设置作为参数，而不是作为数组项，在 dsn 配置中：

  • host

  • username

  • password

  • options 和 driver_options，它们通过选项名称指定。

以下示例展示了如何在 connections 数组项中指定您的MongoDB连接详细信息。

示例 config/database.php MongoDB连接配置
'connections' => [
    'mongodb' => [
        'driver' => 'mongodb',
        'dsn' => 'mongodb+srv//myUser:myPass123@sample.host:27017/',
        'database' => 'sample_mflix',
        'options' => [
            'maxPoolSize' => 20,
            'w' => 'majority',
        ],
        'driver_options' => [
            'serverApi' => 1,
        ],
    ],
    // ...
],

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

连接示例

本节展示了如何通过使用MongoDB Atlas连接字符串来配置Laravel应用程序的DSN。

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

  • 在项目环境配置文件 .env 中添加DSN作为环境变量。将变量值设置为您的Atlas连接字符串。

  • 在配置文件 config/database.php 的 connections 数组中添加您的MongoDB连接条目。将连接条目的 dsn 值设置为引用包含您的DSN的环境变量。

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

示例 .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连接字符串，请按照快速入门教程中的 创建连接字符串 步骤进行。

其他连接到MongoDB的方法

以下部分展示了如何连接到一个不在MongoDB Atlas上托管的单个MongoDB服务器实例或副本集。

在您的本地机器上连接到 MongoDB 服务器

本节展示了当运行 Laravel 应用程序和 MongoDB 服务器在同一个机器上，例如您的本地开发环境时，您可以使用的示例连接字符串。

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

  • 下载、安装并运行 MongoDB 服务器。

  • 获取您的 MongoDB 服务器正在运行的 IP 地址和端口。如果您使用的是 MongoDB 服务器的本地安装默认设置，则 IP 地址为 127.0.0.1，端口为 27017。

  • 设置您的 config/database.php 连接，以便引用环境变量 DB_URI 作为 dsn 的值，如连接示例部分所示。

以下示例显示了您可以添加到 .env 文件中的示例连接字符串，如果您的应用程序连接到默认 IP 地址和端口运行的 MongoDB 服务器

连接到本地 MongoDB 服务器的示例 .env 环境配置。
DB_URI="mongodb://127.0.0.1:27017/";

有关如何下载和安装 MongoDB 服务器的说明，请参阅服务器手册中的安装 MongoDB 社区版。

连接到副本集

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

要连接到副本集部署，指定每个节点的主机名和端口号，用逗号分隔，并将副本集名称作为连接字符串中 replicaSet 参数的值。

本例展示了您可以将连接字符串添加到Laravel应用程序的.env文件中，以连接到副本集，以下是一些示例值

  • 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副本集的信息，请参阅服务器手册中的部署副本集。

直接连接

要强制操作在MongoDB副本集中的特定节点上运行，请指定该节点的连接信息并在连接字符串中设置directConnection参数为true值。

直接连接存在以下限制

  • 不能使用DNS种子列表连接格式的连接字符串。

  • 当指定的主机不是主节点时，写操作会失败。

  • 当主机不是主节点时，您必须在连接选项中指定secondary读取优先级。要了解更多关于此限制的信息，请参阅服务器手册中的secondary read preference entry。

以下示例显示了您可以添加到Laravel应用程序的.env文件中以建立到MongoDB副本集中二级节点的直接连接的连接字符串。以下是一些示例值

  • host2作为二级节点的主机名

  • 27017作为MongoDB节点监听的端口号

启用直接连接的样本.env环境配置
DB_URI="mongodb://host2:27017/?directConnection=true&readPreference=secondary"

返回

连接

下一页

连接选项