(mongodb >=1.0.0)
MongoDB\Driver\Manager::__construct — Cria um novo gerenciador MongoDB
$uri
= null
, ?array $uriOptions
= null
, ?array $driverOptions
= null
)Constrói um novo objeto MongoDB\Driver\Manager com as opções especificadas.
Nota: De acordo com a » Especificação de descoberta e monitoramento de servidor, esse construtor não executa E/S. As conexões serão inicializadas sob demanda, quando a primeira operação for executada.
Nota: Ao especificar qualquer opção de URI SSL ou TLS por meio da string de conexão ou do parâmetro
uriOptions
, a extensão habilitará implicitamente o TLS para suas conexões. Para evitar isso, a opçãotls
deve ser desabilitada explicitamente ou nenhuma opção de TLS deve ser especificada.
Nota: Em plataformas Unix, a extensão é sensível a scripts que usam a chamada de sistema fork() sem chamar também exec(). Os usuários são aconselhados a não reusar instâncias de MongoDB\Driver\Manager em um processo filho bifurcado.
uri
Uma URI de conexão » mongodb://:
mongodb://[usuário:senha@]servidor1[:porta1][,servidor2[:porta2],...[,servidorN[:portaN]]][/[BD_autenticacao_padrão][?opções]]
O padrão é "mongodb://127.0.0.1:27017"
se não especificado.
Para obter detalhes sobre as opções de URI suportadas, consulte » Opções de string de conexão no manual do MongoDB. » Opções de pool de conexões não são suportadas, pois a extensão não implementa pools de conexões.
O uri
é um URL, portanto, quaisquer caracteres especiais
em seus componentes precisam ser codificados em URL de acordo com a
» RFC 3986. Isto é particularmente
relevante para o nome de usuário e a senha, que muitas vezes podem incluir caracteres
especiais como @
, :
ou
%
. Ao conectar através de um soquete de domínio Unix, o caminho
do soquete pode conter caracteres especiais, como barras, e deve ser codificado.
A função rawurlencode() pode ser usada para codificar
partes constituintes do URI.
O componente defaultAuthDb
pode ser usado para especificar o
nome do banco de dados associado às credenciais do usuário; entretanto, a
opção de URI authSource
terá prioridade se especificada.
Se nem defaultAuthDb
nem
authSource
forem especificados, o banco de dados admin
será usado por padrão. O componente defaultAuthDb
não tem efeito na ausência de credenciais do usuário.
uriOptions
» Opções de string de conexão
adicionais,
que substituirão quaisquer opções com o mesmo nome no
parâmetro uri
.
Opção | Tipo | Descrição |
---|---|---|
appname | string |
O MongoDB 3.4+ tem a capacidade de anotar conexões com metadados fornecidos pelo cliente conectado. Esses metadados são incluídos nos registros do servidor ao estabelecer uma conexão e também incluídos nos registros de consultas lentas quando a perfilagem do banco de dados está habilitada. Esta opção pode ser usada para especificar um nome de aplicação, que será incluído nos metadados. O valor não pode exceder 128 caracteres. |
authMechanism | string |
O mecanismo de autenticação que o MongoDB usará para autenticar a conexão. Para obter detalhes adicionais e uma lista de valores suportados, consulte » Opções de autenticação no manual do MongoDB. |
authMechanismProperties | array |
Propriedades do mecanismo de autenticação selecionado. Para obter detalhes adicionais e uma lista de propriedades suportadas, consulte a » Especificação de autenticação do driver.
|
authSource | string |
O nome do banco de dados associado às credenciais do usuário. O padrão
é o componente de banco de dados do URI de conexão ou o banco de dados
Para mecanismos de autenticação que delegam o armazenamento de credenciais a
outros serviços (por exemplo, GSSAPI), deve ser
|
canonicalizeHostname | bool |
Se
Esta opção é um sinônimo descontinuado para a propriedade
|
compressors | string |
Uma lista priorizada e delimitada por vírgulas de compressores que o cliente deseja usar. As mensagens só serão compactadas se o cliente e o servidor compartilharem algum compressor em comum, e o compressor usado em cada direção dependerá da configuração individual do servidor ou driver. Consulte a » Especificação de compactação do driver para obter mais informações. |
connectTimeoutMS | int |
O tempo em milissegundos para tentar uma conexão antes de atingir o tempo limite. O padrão é 10000 milissegundos. |
directConnection | bool |
Esta opção pode ser usada para controlar o comportamento de descoberta
do conjunto de réplicas quando apenas um único servidor é fornecido na string de conexão. Por
padrão, fornecer um único membro na string de conexão
estabelecerá uma conexão direta ou descobrirá membros adicionais
dependendo se a opção de URI |
gssapiServiceName | string |
Define o nome do serviço Kerberos ao conectar-se a instâncias MongoDB
Kerberizadas. Este valor deve corresponder ao nome do serviço definido nas instâncias
do MongoDB (ou seja,
parâmetro do servidor » saslServiceName).
O padrão é
Esta opção é um sinônimo descontinuado para a propriedade
|
heartbeatFrequencyMS | int |
Especifica o intervalo em milissegundos entre as verificações do driver da topologia MongoDB, contado do final da verificação anterior até o início da próxima. O padrão é 60000 milissegundos. Pela » Especificação de descoberta e monitoramento de servidor, esse valor não pode ser inferior a 500 milissegundos. |
journal | bool |
Corresponde ao parâmetro |
loadBalanced | bool |
Especifica se o driver está se conectando a um cluster MongoDB
por meio de um balanceador de carga. Se for igual a |
localThresholdMS | int |
O tamanho em milissegundos da janela de latência para selecionar entre várias instâncias adequadas do MongoDB ao resolver uma preferência de leitura. O padrão é 15 milissegundos. |
maxStalenessSeconds | int |
Corresponde ao
Se especificada, a inatividade máxima deve ser um número inteiro com sinal de 32 bits
maior ou igual a
|
password | string | A senha do usuário que está sendo autenticado. Esta opção é útil se a senha contiver caracteres especiais, que de outra forma precisariam ser codificados em URL para o URI de conexão. |
readConcernLevel | string |
Corresponde ao parâmetro level da preocupação
de leitura. Especifica o nível de isolamento de leitura. Para obter detalhes, consulte
MongoDB\Driver\ReadConcern.
|
readPreference | string |
Corresponde ao parâmetro |
readPreferenceTags | array |
Corresponde ao parâmetro
|
replicaSet | string |
Especifica o nome do conjunto de réplicas. |
retryReads | bool |
Especifica se o driver deve ou não repetir automaticamente
determinadas operações de leitura que falham devido a erros transitórios de rede
ou eleições de conjunto de réplicas. Esta funcionalidade requer o MongoDB 3.6+.
O padrão é Consulte a » Especificação de leituras repetíveis para mais informações. |
retryWrites | bool |
Especifica se o driver deve ou não repetir automaticamente
determinadas operações de gravação que falham devido a erros transitórios de rede
ou eleições de conjunto de réplicas. Esta funcionalidade requer o MongoDB 3.6+.
O padrão é Consutle » Gravações Repetíveis no manual do MongoDB para obter mais informações. |
safe | bool |
Se Esta opção foi descontinuada e não deve ser usada. |
serverSelectionTimeoutMS | int |
Especifica quanto tempo, em milissegundos, deve-se bloquear para seleção de servidor antes de lançar uma exceção. O padrão é 30000 milissegundos. |
serverSelectionTryOnce | bool |
Quando |
socketCheckIntervalMS | int |
Se um soquete não tiver sido usado recentemente, o driver precisará verificá-lo através
do comando |
socketTimeoutMS | int |
O tempo em milissegundos para tentar enviar ou receber em um soquete antes de atingir o tempo limite. O padrão é 300000 milissegundos (ou seja, cinco minutos). |
srvMaxHosts | int |
O número máximo de resultados de SRV a serem selecionados aleatoriamente ao preencher
inicialmente a lista de valores iniciais ou, durante a sondagem de SRV, ao incluir novos servidores na
topologia. O padrão é |
srvServiceName | string |
O nome do serviço a ser usado para consulta de SRV na descoberta inicial da
lista de valores iniciais de DNS e na sondagem de SRV. O padrão é |
ssl | bool |
Inicia a conexão com TLS/SSL se for igual a
Esta opção é um apelido descontinuado para a opção de URI
|
tls | bool |
Inicia a conexão com TLS/SSL se for igual a |
tlsAllowInvalidCertificates | bool |
Especifica se o driver deve ou não apresentar erro quando o certificado
TLS do servidor for inválido. O padrão é Aviso
Desabilitar a validação de certificado cria uma vulnerabilidade. |
tlsAllowInvalidHostnames | bool |
Especifica se o driver deve ou não apresentar erro quando há uma
incompatibilidade entre o nome do host do servidor e o nome do host especificado pelo
certificado TLS. O padrão é Aviso
Desabilitar a validação de certificado cria uma vulnerabilidade. Permitir nomes de servidores inválidos pode expor o driver a um » ataque MITM. |
tlsCAFile | string |
Caminho para arquivo com uma única autoridade de certificação ou um pacote de autoridades de certificação a ser considerado confiável ao fazer uma conexão TLS. O armazenamento de certificados do sistema será usado por padrão. |
tlsCertificateKeyFile | string |
Caminho para o arquivo de certificado do cliente ou arquivo de chave privada do cliente; caso ambos sejam necessários, os arquivos deverão ser concatenados. |
tlsCertificateKeyFilePassword | string |
Senha para descriptografar a chave privada do cliente (ou seja,
opção de URI |
tlsDisableCertificateRevocationCheck | bool |
Se |
tlsDisableOCSPEndpointCheck | bool |
Se |
tlsInsecure | bool |
Relaxa as restrições de TLS tanto quanto possível. Especificar Aviso
Desabilitar a validação de certificado cria uma vulnerabilidade. Permitir nomes de servidores inválidos pode expor o driver a um » ataque MITM. |
username | string | O nome do usuário que está sendo autenticado. Esta opção é útil se o nome de usuário contiver caracteres especiais, que de outra forma precisariam ser codificados em URL para o URI de conexão. |
w | int|string |
Corresponde ao parâmetro |
wTimeoutMS | int|string |
Corresponde ao parâmetro
Se especificado, |
zlibCompressionLevel | int |
Especifica o nível de compactação a ser usado para o compressor zlib. Esta
opção não tem efeito se |
driverOptions
Opção | Tipo | Descrição | ||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
allow_invalid_hostname | bool |
Desativa a validação do nome do host se Permitir nomes de servidores inválidos pode expor o driver a um » ataque MITM.
Esta opção é um sinônimo descontinuado para a opção de URI
|
||||||||||||||||||||||||||||||
autoEncryption | array |
Fornece opções para ativar a criptografia automática em nível de campo do lado do cliente.
As seguintes opções são suportadas:
|
||||||||||||||||||||||||||||||
ca_dir | string |
Caminho para um diretório de certificado com hash correto. O armazenamento de certificados do sistema será usado por padrão. |
||||||||||||||||||||||||||||||
ca_file | string |
Caminho para arquivo com uma única autoridade de certificação ou um pacote de autoridades de certificação a ser considerado confiável ao fazer uma conexão TLS. O armazenamento de certificados do sistema será usado por padrão.
Esta opção é um sinônimo descontinuado para a opção de URI
|
||||||||||||||||||||||||||||||
context | resource |
As opções de contexto SSL a serem usadas como substitutas se uma opção de driver ou sua opção de URI equivalente, se houver, não for especificada. Observe que a extensão não consulta o contexto de fluxo padrão (ou seja, stream_context_get_default()). As seguintes opções de contexto são suportadas:
Esta opção é suportada para compatibilidade com versões anteriores, mas deve ser considerada obsoleta. |
||||||||||||||||||||||||||||||
crl_file | string | Caminho para um arquivo de lista de certificados revogados. | ||||||||||||||||||||||||||||||
disableClientPersistence | bool |
Se
|
||||||||||||||||||||||||||||||
driver | array |
Permite que uma biblioteca de nível superior anexe seus próprios metadados ao
"handshake" com o servidor. Por padrão, a extensão envia seu próprio nome,
versão e plataforma (ou seja, versão PHP) nesta comunicação inicial. Strings
podem ser especificadas para as chaves
|
||||||||||||||||||||||||||||||
pem_file | string |
Caminho para um certificado codificado em PEM a ser usado para autenticação do cliente.
Esta opção é um sinônimo descontinuado para a opção de URI
|
||||||||||||||||||||||||||||||
pem_pwd | string |
Senha para o certificado codificado em PEM (se aplicável).
Esta opção é um sinônimo descontinuado para a opção de URI
|
||||||||||||||||||||||||||||||
serverApi | MongoDB\Driver\ServerApi |
Esta opção é usada para declarar uma versão da API do servidor para o gerenciador. Se omitida, nenhuma versão da API será declarada. |
||||||||||||||||||||||||||||||
weak_cert_validation | bool |
Desativa a validação do certificado se for igual a
Esta opção é um sinônimo descontinuado para a opção de URI
|
uri
for inválido
Versão | Descrição |
---|---|
PECL mongodb 1.16.0 |
O provedor AWS KMS para criptografia do lado do cliente agora aceita uma
opção
Aicionada a opção
Se um documento vazio for especificado para o provedor KMS |
PECL mongodb 1.15.0 |
Se um documento vazio for especificado para o provedor KMS |
PECL mongodb 1.14.0 |
Adicionadas as opções de criptografia automática |
PECL mongodb 1.13.0 |
Adicionadas as opções de URI |
PECL mongodb 1.12.0 |
KMIP agora é suportado como um provedor KMS para criptografia do lado do cliente e
pode ser configurado no campo |
PECL mongodb 1.11.0 |
Adicionada a opção de URI |
PECL mongodb 1.10.0 |
Adicionada a opção de driver
Azure e GCP agora são suportados como provedores KMS para criptografia
do lado do cliente e podem ser configurados no
campo |
PECL mongodb 1.8.0 |
Adicionadas as opções de URI
Adicionada a opção de driver |
PECL mongodb 1.7.0 |
Adicionada a opção de driver
Especificar qualquer opção SSL ou TLS por meio do parâmetro |
PECL mongodb 1.6.0 |
Adicionadas as opções de URI
A opção de URI
Especificar qualquer opção de URI SSL ou TLS por meio da string de conexão ou
do parâmetro |
PECL mongodb 1.5.0 |
|
PECL mongodb 1.4.0 |
Adicionadas as opções de URI |
PECL mongodb 1.3.0 |
O parâmetro |
PECL mongodb 1.2.0 |
O padrão para o parâmetro
Adicionada a opção de URI
Adicionadas as opções de driver
A API de Fluxos do PHP não é mais usada para comunicação de soquete. A
opção de URI |
PECL mongodb 1.1.0 |
O parâmetro |
Exemplo #1 Exemplos básicos de MongoDB\Driver\Manager::__construct()
Conexão a um nó independente do MongoDB:
<?php
$manager = new MongoDB\Driver\Manager("mongodb://example.com:27017");
?>
Conectando-se ao nó independente do MongoDB por meio de um soquete de domínio Unix. O caminho do soquete pode incluir caracteres especiais como barras e deve ser codificado com rawurlencode().
<?php
$manager = new MongoDB\Driver\Manager("mongodb://" . rawurlencode("/tmp/mongodb-27017.sock"));
?>
Conectando-se a um conjunto de réplicas:
<?php
$manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");
?>
Conectando-se a um cluster fragmentado (ou seja, uma ou mais instâncias do mongos):
<?php
$manager = new MongoDB\Driver\Manager("mongodb://mongos1.example.com,mongos2.example.com/");
?>
Conectando-se ao MongoDB com credenciais de autenticação para um usuário e banco de dados específicos:
<?php
$manager = new MongoDB\Driver\Manager("mongodb://meuUsuario:minhaSenha@example.com/?authSource=nomeBancoDeDados");
?>
Conectando-se ao MongoDB com credenciais de autenticação para um usuário e
banco de dados específicos, onde o nome de usuário ou senha inclui caracteres
especiais (por exemplo, @
, :
,
%
). No exemplo a seguir, a string de senha
myp@ss:w%rd
foi escapada manualmente; entretanto,
rawurlencode() também pode ser usado para escapar componentes URI
que podem conter caracteres especiais.
<?php
$manager = new MongoDB\Driver\Manager("mongodb://meuUsuario:myp%40ss%3Aw%25rd@example.com/?authSource=nomeBancoDeDados");
?>
Conectando-se ao MongoDB com autenticação X509:
<?php
$manager = new MongoDB\Driver\Manager(
"mongodb://example.com/?ssl=true&authMechanism=MONGODB-X509",
[],
[
"pem_file" => "/caminho/para/cliente.pem",
]
);
?>