real_connect

Neste artigo, vamos discutir o método real_connect() no PHP, utilizado para estabelecer uma conexão com um banco de dados MySQL. (O equivalente procedural é mysqli_real_connect().)

Esta página aborda o que diferencia real_connect() de um simples mysqli_connect(), a lista completa de parâmetros, como habilitar SSL e outros flags de conexão, e os erros mais comuns.

O que é real_connect() e por que usá-lo?

O método real_connect() abre uma conexão com um servidor MySQL, assim como mysqli_connect(). A principal diferença é que real_connect() opera sobre um identificador de conexão que você já criou com mysqli_init(), em vez de criar e conectar em uma única etapa.

Essa etapa extra é importante porque oferece uma janela entre a criação do identificador e a conexão, onde é possível configurar opções que só podem ser definidas antes de a conexão ser estabelecida. Use real_connect() (em vez de mysqli_connect()) quando precisar:

• Definir opções de conexão com mysqli_options() — por exemplo, um timeout de conexão (MYSQLI_OPT_CONNECT_TIMEOUT) ou suporte a infile local.
• Habilitar uma conexão SSL/TLS com ssl_set() e o flag MYSQLI_CLIENT_SSL.
• Passar flags de cliente como MYSQLI_CLIENT_COMPRESS ou MYSQLI_CLIENT_FOUND_ROWS.
• Abrir uma conexão persistente prefixando o host com p:.

Se nenhum desses casos se aplica, o mysqli_connect() mais simples é perfeitamente adequado.

Uso básico

real_connect() sempre segue um padrão de duas etapas: criar o identificador e depois conectar. Veja a abordagem orientada a objetos:

<?php
$mysqli = mysqli_init();

if (!$mysqli) {
    die('mysqli_init failed');
}

if (!$mysqli->real_connect('localhost', 'username', 'password', 'database')) {
    die('Connect Error (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error);
}

echo 'Success... ' . $mysqli->host_info . "\n";

$mysqli->close();
?>

Primeiro criamos um identificador MySQLi com mysqli_init() e verificamos se teve sucesso. Em seguida, chamamos real_connect() no objeto $mysqli para conectar. Se falhar, reportamos o erro com connect_errno e connect_error e encerramos; em caso de sucesso, exibimos as informações do host e liberamos a conexão com close().

Parâmetros

real_connect() aceita os seguintes parâmetros, todos opcionais, nesta ordem:

Nota: com a API OO, o identificador é o objeto, então o primeiro argumento é o host. Com o procedural mysqli_real_connect($link, $host, ...), o link é passado primeiro.

Definindo opções antes de conectar

Este é o principal motivo pelo qual real_connect() existe. Configure o identificador com mysqli_options() entre init e real_connect:

<?php
$mysqli = mysqli_init();

// These can only be set before connecting:
$mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);
$mysqli->options(MYSQLI_INIT_COMMAND, "SET autocommit = 0");

if (!$mysqli->real_connect('localhost', 'username', 'password', 'database')) {
    die('Connect Error (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error);
}

echo 'Connected with a 5-second timeout.';
$mysqli->close();
?>

Conectando com SSL e flags de cliente

O sétimo parâmetro é uma bitmask de flags de cliente. Para exigir uma conexão criptografada, configure os certificados com ssl_set() e passe MYSQLI_CLIENT_SSL:

<?php
$mysqli = mysqli_init();

$mysqli->ssl_set(null, null, '/path/to/ca-cert.pem', null, null);

$mysqli->real_connect(
    'db.example.com', 'username', 'password', 'database',
    3306, null,
    MYSQLI_CLIENT_SSL
);

echo 'Encrypted connection established.';
$mysqli->close();
?>

Flags comuns que podem ser combinados com |:

• MYSQLI_CLIENT_SSL — usar criptografia SSL/TLS.
• MYSQLI_CLIENT_COMPRESS — usar o protocolo comprimido.
• MYSQLI_CLIENT_FOUND_ROWS — retornar linhas correspondidas em vez de linhas alteradas.

Conexões persistentes

Prefixar o host com p: reutiliza uma conexão existente do pool entre requisições em vez de abrir uma nova a cada vez, o que pode reduzir a sobrecarga de conexão em servidores com alto volume de acessos:

<?php
$mysqli = mysqli_init();
$mysqli->real_connect('p:localhost', 'username', 'password', 'database');
?>

Erros comuns

• Esquecer o mysqli_init(). real_connect() deve ser chamado sobre um identificador retornado por mysqli_init(). Chamá-lo em um new mysqli() recém-construído que já está conectado irá falhar.
• Verificar a propriedade de erro errada. Antes de a conexão existir, use connect_errno / connect_error, não errno / error.
• Definir opções tarde demais. Opções como o timeout de conexão não têm efeito depois que a conexão está aberta — elas devem ser definidas antes de real_connect().

Conclusão

O método real_connect() estabelece uma conexão MySQL a partir de um identificador criado com mysqli_init(), oferecendo a oportunidade de configurar timeouts, SSL e flags de cliente que um mysqli_connect() de uma única etapa não permite. Uma vez conectado, você pode executar instruções com query() e selecionar um banco de dados com select_db().

Prática