MongoClient::__construct

(PECL mongo >=1.3.0)

MongoClient::__construct — Создает новый объект подключения к базе данных

Расширение, задающее этот метод, объявлено устаревшим. Вместо него используйте расширение MongoDB. Есть такие альтернативы:

Описание

public MongoClient::__construct ([ string $server = "mongodb://localhost:27017" [, array $options = array("connect" => TRUE) [, array $driver_options ]]] )

Если параметры не переданы, то подключается к "localhost:27017" (или к тому, что было указано в php.ini для mongo.default_host и mongo.default_port).

server должен иметь форму: 

mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db

Строка подключения всегда начинается с mongodb://, чтобы указать, что это строка подключения в этой форме.

Если указаны username и password, конструктор попытается аутентифицировать соединение с базой данных перед возвратом. Имя пользователя и пароль не являются обязательными и должны сопровождаться @, если указаны.

Должен быть указан хотя бы один хост (порт необязательный, всегда по умолчанию 27017), и к нему может быть подключено столько хостов, сколько необходимо. Имена хостов разделены запятыми, и конструктор вернется успешно, если он подключен хотя бы к одному хосту. Если он не может подключиться ни к одному из хостов, он выдаст исключение MongoConnectionException. Пожалуйста, обратитесь к разделу наборы реплик для получения информации о том, как подключиться к наборам реплик.

Если вы указали имя пользователя и пароль, вы можете указать базу данных для аутентификации. Если db не указан, будет использоваться "admin".

Необязательная строка запроса может использоваться для указания дополнительных параметров. Те же параметры поддерживаются и в массиве параметров, поэтому они там переписываются. Ниже приведены примеры, как установить эти параметры.

Одна часть параметров определяет, как драйвер считывает данные со вторичных узлов в среде набора реплик. Дополнительная информация о том, как работают эти настройки чтения, также доступна на странице документации по настройкам чтения.

Список параметров

server

Имя сервера.

options

Массив опций для подключения. В настоящее время доступны следующие варианты:

  • "authMechanism"

    Доступные механизмы:

    authMechanism Описание Доступность
    MONGODB-CR Проверка подлинности с использованием механизма ответа на вызов. Это значение по умолчанию. Все версии MongoDB
    MONGODB-X509 Аутентификация с использованием сертификатов X.509 MongoDB 2.6. Доступно только когда OpenSSL включен
    PLAIN Аутентификация с использованием незашифрованного простого имени пользователя + пароля. Должен использоваться по SSL-соединениям. Обычно используется MongoDB для входа через сторонний сервер LDAP MongoDB Enterprise 2.4. Драйвер должен быть скомпилирован с CyrusSASL2
    GSSAPI Аутентификация через системы Kerberos MongoDB Enterprise 2.4. Драйвер должен быть скомпилирован с CyrusSASL2
    SCRAM-SHA-1 Аутентификация через SCRAM-SHA-1 MongoDB 3.0.

  • "authSource"

    Должно быть установлено имя базы данных, где пользователь определен.

  • "connect"

    Если конструктор должен подключиться, прежде чем вернуться. По умолчанию TRUE. Если установлено значение FALSE, драйвер будет автоматически подключаться к серверу всякий раз, когда необходимо выполнить запрос. Кроме того, вы можете запустить MongoClient::connect() вручную.

    Внимание

    Эта опция не поддерживается через строку подключения.

  • "connectTimeoutMS"

    Сколько времени может занять соединение до истечения времени ожидания в миллисекундах. По умолчанию 60000 (60 секунд).

    Если указано -1, время ожидания соединения не будет применяться, и PHP будет использовать default_socket_timeout.

  • "db"

    Здесь можно указать базу данных для аутентификации, не включая ее в список хостов. Это переопределяет базу данных, указанную в списке хостов.

  • "fsync"

    Если установлен "fsync", все операции записи будут блокироваться до тех пор, пока база данных не сбросит изменения на диск. Это замедляет операции записи, но гарантирует, что запись прошла успешно и что операции могут быть восстановлены в случае полного сбоя системы.

    Если на сервере MongoDB включено ведение журнала, эта опция идентична "journal". Если ведение журнала не включено, этот параметр гарантирует, что операции записи будут синхронизированы с файлами базы данных на диске.

    Замечание: Если ведение журнала включено, пользователям настоятельно рекомендуется использовать опцию "journal" вместо "fsync". Не используйте одновременно "fsync" и "journal", так как это приведет к ошибке.

  • "journal"

    Если установлен "journal", все операции записи будут блокироваться до тех пор, пока база данных не сбросит изменения в журнал на диске. Это замедляет операции записи, но гарантирует, что запись прошла успешно и что операции могут быть восстановлены в случае полного сбоя системы.

    Замечание: Если эта опция используется и ведение журнала отключено, MongoDB 2.6+ вызовет ошибку и запись не удастся; старые версии сервера просто игнорируют эту опцию.

  • "gssapiServiceName"

    Устанавливает » субъект службы Kerberos. Применяется только когда authMechanism=GSSAPI. По умолчанию "mongodb".

  • "password"

    Здесь можно указать пароль, а не включать его в список хостов. Особенно полезно, если в пароле есть «@». Это отменяет пароль, установленный в списке хостов.

  • "readPreference"

    Определяет предпочтения чтения. Предпочтения чтения предоставляют вам контроль, из которого могут быть считаны вторичные данные.

    Допустимые значения: MongoClient::RP_PRIMARY, MongoClient::RP_PRIMARY_PREFERRED, MongoClient::RP_SECONDARY, MongoClient::RP_SECONDARY_PREFERRED и MongoClient::RP_NEAREST.

    Смотрите документацию по Read Preference для получения дополнительной информации.

  • "readPreferenceTags"

    Определяет теги предпочтения чтения в виде массива строк. Теги могут использоваться в сочетании с опцией readPreference для дальнейшего контроля, из каких вторичных данных могут быть считаны.

    Смотрите документацию по предпочтениям чтения для получения дополнительной информации.

  • "replicaSet"

    Имя реплики, к которой нужно подключиться. Если указано, основной сервер будет определен автоматически. Это означает, что драйвер может в конечном итоге подключиться к серверу, которого даже нет в списке. Смотрите пример набора реплик ниже для подробностей.

  • "secondaryAcceptableLatencyMS"

    При чтении с вторичного сервера (с использованием ReadPreferences) не читайте с вторичных серверов, о которых известно, что они находятся на более чем secondaryAcceptableLatencyMS, вдали от нас. По умолчанию 15

  • "socketTimeoutMS"

    Сколько времени может занять операция сокета (чтение или запись) до истечения времени ожидания в миллисекундах. По умолчанию 30000 (30 секунд).

    Если указано -1, операции с сокетом могут блокироваться бесконечно. Опция также может быть установлена для каждой операции, используя MongoCursor::timeout() для запросов или опцию "socketTimeoutMS" для методов записи.

    Замечание: Время ожидания на стороне клиента. Если время операции записи истекло, нет способа узнать, обработал ли сервер запись или нет, так как вместо возврата результата записи, будет выдано исключение MongoCursorTimeoutException.

  • "ssl"

    Логическое значение, указывающее, хотите ли вы включить SSL для соединений с MongoDB. Дополнительные параметры, такие как сертификаты, могут быть установлены с помощью Опции контекста SSL.

  • "username"

    Здесь можно указать имя пользователя, а не включать его в список хостов. Особенно полезно, если в имени пользователя есть ":". Это переопределяет имя пользователя, установленное в списке хостов.

  • "w"

    Опция w задает гарантии записи для драйвера, который определяет, как долго драйвер блокирует при записи. Значением по умолчанию является 1.

    Этот параметр применим при подключении как к отдельным серверам, так и к наборам реплик. Положительное значение контролирует, как много узлов должно подтвердить запись, прежде чем драйвер продолжит работу. Значение 1 потребует, чтобы единственный сервер или основной сервер (в наборе реплик) подтвердили операцию записи. Значение 3 приведет к блокировке драйвера до тех пор, пока запись не будет применена как к основному, так и к двум вторичным серверам (в наборе реплик).

    Строковое значение используется для управления тем, какие наборы тегов учитываются при записи. "majority" является особенным и гарантирует, что операция записи была применена к большинству (более 50%) участвующих узлов.

  • "wTimeoutMS"

    Параметр указывает ограничение времени в миллисекундах для гарантии записи. Это применимо только для операций записи, где "w" больше 1, поскольку время ожидания относится к репликации. Если проблема с записью не будет удовлетворена в течение срока, будет выдано исключение MongoCursorException. Значение 0 может быть указано для блокировки на неопределенный срок. Значением по умолчанию является 10000 (десять секунд).

Следующие параметры устарели и больше не должны использоваться:

  • "slaveOkay"

    Устаревшее. Пожалуйста, используйте предпочтения чтения.

  • "timeout"

    Устаревший псевдоним для "connectTimeoutMS".

  • "wTimeout"

    Устаревший псевдоним для "wTimeoutMS".

driver_options

Массив опций для драйвера MongoDB. Опции включают настройку параметров контекста SSL соединения или регистрацию callback-функций.

Возвращаемые значения

Возвращает новый объект подключения к базе данных.

Ошибки

Выдает исключение MongoConnectionException, если он пытается и не может подключиться к базе данных для всех заданных имен хостов. Он также выдаст исключение MongoConnnectionException, если указано неверное имя пользователя или пароль. Смотрите документацию MongoConnectionException для общих исключений и их причин.

Примеры

Пример #1 Пример набора реплик MongoClient::__construct()

В этом примере показано, как подключить драйвер к набору реплик. Предполагается, что существует набор из трех серверов: sf1.example.com, sf2.example.com и ny1.example.com. Основным может быть любой из этих серверов.

<?php

// передаем разделенный запятыми список имен серверов конструктору
// Обратите внимание, что нам не нужно передавать все члены набора реплик драйверу
// выведет полный список.
$m1 = new MongoClient("mongodb://sf2.example.com,ny1.example.com", array("replicaSet" => "myReplSet"));

?>

Если текущий основной сервер отказывает, драйвер выяснит, какой вторичный сервер стал новым основным, и автоматически начнет использовать это соединение. Автоматическое переключение при сбое не будет работать правильно, если replicaSet не указан.

Чтобы драйвер мог подключиться к набору реплик, должен быть хотя бы один начальный элемент в начальном списке.

Если вы включите источника из двух отдельных наборов реплик, поведение будет не определенным.

Смотрите » базовую документацию по наборам реплик для получения дополнительной информации.

Пример #2 Подключение к доменному сокету

В версии 1.0.9+ вы можете использовать доменный сокет UNIX для подключения к экземпляру MongoDB, работающему локально. Это должно быть немного быстрее, чем при использовании сетевого подключения.

В версии 1.5.0 сервер MongoDB автоматически открывает сокет по адресу /tmp/mongodb-<port>.sock. Вы можете подключиться к этому, указав путь в строке подключения:

<?php

// Сервер MongoDB, работающий локально на порте 20000
$m = new MongoClient("mongodb:///tmp/mongodb-20000.sock");

?>

Вы можете комбинировать это с любыми другими связями, которые вы хотите:

<?php

// пробуем подключиться к сокету домена, открываем соединение с локальным хостом
$m = new MongoClient("mongodb:///tmp/mongodb-27017.sock,localhost:27017");

?>

Пример #3 Пример аутентификации MongoClient::__construct()

Пользователь должен существовать в базе данных "admin", прежде чем пытаться использовать аутентификацию. Вы можете создать его с помощью оболочки Mongo, выполнив: 

> use admin
switched to db admin
> db.addUser("testUser", "testPass");
{
        "_id" : ObjectId("4b21272fd9ab21611d19095c"),
        "user" : "testUser",
        "pwd" : "03b9b27e0abf1865e2f6fcbd9845dd59"
}
>

После создания пользователя, в данном случае, имени пользователя "testUser" и пароля "testPass", вы можете создать аутентифицированное соединение:

<?php

$m = new MongoClient("mongodb://testUser:testPass@localhost");

?>

Пример #4 Пример предпочтения чтения в MongoClient::__construct()

<?php

// Предпочтем ближайший сервер в "восточном" дата-центре
$uri  = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
?>

Смотрите раздел предпочтениям чтения для получения дополнительной информации.

Пример #5 Пример опций MongoClient::__construct()

Опции могут передаваться как через строку запроса в строке подключения, так и в виде массива, передаваемого в качестве второго аргумента конструктору.

Здесь мы устанавливаем для опции журнала значение true, а для readPreference - вторичный сервер, предпочитаемый по умолчанию для всех операций записи:

<?php
$m = new MongoClient("mongodb://localhost/?journal=true&readPreference=secondary");
?>

И теперь мы делаем то же самое, но с помощью массива опций:

<?php
$options = array(
    'journal' => true,
    'readPreference' => 'secondary',
);
$m = new MongoClient("mongodb://localhost/", $options);
?>

Пример #6 Пример предпочтения чтения в MongoClient::__construct()

<?php

// Предпочтем ближайший сервер в "восточном" дата-центре
$uri  = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new MongoClient($uri, array('replicaSet' => 'rs'));
?>

Смотрите раздел предпочтениям чтения для получения дополнительной информации.

Список изменений

Версия Описание
1.6.0

Добавлена поддержка "SCRAM-SHA-1" в опции "authMechanism".

1.5.0

Добавлены "authMechanism", "gssapiServiceName" и "secondaryAcceptableLatencyMS".

1.4.0

Добавлена опция "ssl" и поддержка подключения по SSL.

Добавлена опция "wTimeoutMS", которая заменяет "wTimeout".

Выдает E_DEPRECATED, при использовании "slaveOkay" или "timeout".

1.5.0

Добавлена опция "authSource".

1.3.4

Добавлены опции "connectTimeoutMS" и "socketTimeoutMS".

1.3.0

Добавлены опции "readPreference", "readPreferenceTags", "w", и "wTimeout".

1.2.0

Добавлены опции "username" и "password".

Удалена опция "persist", так как все соединения теперь являются постоянными. Ее все еще можно использовать, но это ни на что не влияет.

"persist"

Когда соединение должно быть постоянным. Если установлено, соединение будет постоянным. Строковое представление значения используется в качестве идентификатора для соединения, поэтому два экземпляра MongoClient, которые инициализируются array("persist" => "foobar"), будут использовать одно и то же соединение с базой данных, тогда как экземпляр, инициализированный array("persist" => "barbaz"), будет использовать другое соединение с базой данных.

Опция "replicaSet" теперь принимает строку, а не логическое значение.

1.0.9 Добавлена опция "replicaSet".
1.0.2

Изменен конструктор, чтобы принимать массив опций. До версии 1.0.2 конструктор принимал следующие параметры:

server

Имя сервера.

connect

Необязательный логический параметр, указывающий, должен ли конструктор подключаться к базе данных перед возвратом. По умолчанию TRUE.

persistent

Если соединение должно быть постоянным.

paired

Если соединение должно быть сопряжено.