init

A função mysqli_init() aloca e inicializa um objeto MySQLi sem abrir uma conexão com o banco de dados. É o primeiro passo de um processo de conexão em duas etapas: você cria o objeto, ajusta suas opções de baixo nível e somente então conecta com mysqli_real_connect(). Esta página explica sua sintaxe, valor de retorno, quando você realmente precisa dela e as armadilhas que costumam pegar as pessoas.

Sintaxe

mysqli_init(): mysqli|false

No estilo orientado a objetos não há um método dedicado — new mysqli() (chamado sem argumentos) realiza a mesma inicialização:

$mysqli = mysqli_init();   // procedural
$mysqli = new mysqli();    // object-oriented equivalent

• Parâmetros: nenhum.
• Valor de retorno: um objeto mysqli novo e não conectado em caso de sucesso, ou false em caso de falha. (Desde o PHP 8.1, a forma procedural é apenas um alias simples de new mysqli() e lança uma exceção em caso de falha, em vez de retornar false, em conformidade com as configurações de mysqli_report().)

Por que mysqli_init() existe

Quando você chama new mysqli("localhost", "user", "pass", "db") com argumentos, o PHP inicializa o objeto e conecta em uma única etapa. Isso é conveniente, mas não deixa nenhuma janela para configurar opções que precisam ser definidas antes do handshake — timeouts de conexão, um comando inicial SET NAMES, SSL ou suporte a local-infile.

mysqli_init() separa essas duas fases:

1. Inicializar o objeto com mysqli_init().
2. Configurar com mysqli_options() (e SSL via mysqli_ssl_set() se necessário).
3. Conectar com mysqli_real_connect().

Se você não precisar de nenhuma opção de pré-conexão, ignore mysqli_init() completamente e passe as credenciais diretamente para new mysqli() — é mais curto e igualmente correto.

Exemplo básico

Este é o fluxo de trabalho procedural canônico. Observe que mysqli_options() fica entre o init e o connect:

<?php
$mysqli = mysqli_init();

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

// Run on every new connection — must be set before connecting.
mysqli_options($mysqli, MYSQLI_INIT_COMMAND, "SET NAMES 'utf8mb4'");

// Give up after 5 seconds instead of hanging.
mysqli_options($mysqli, MYSQLI_OPT_CONNECT_TIMEOUT, 5);

if (!mysqli_real_connect($mysqli, "localhost", "username", "password", "database")) {
    echo "Failed to connect to MySQL: " . mysqli_connect_error();
    exit;
}

echo "Connected. Server version: " . mysqli_get_server_info($mysqli);

mysqli_close($mysqli);
?>

O fluxo é: criar o objeto, definir as opções que devem preceder o handshake e, em seguida, conectar. Verificamos o resultado de mysqli_real_connect() e lemos o motivo da falha com mysqli_connect_error(). Por fim, mysqli_close() libera a conexão.

Crítico: as opções passadas para mysqli_options() só têm efeito se forem definidas antes de mysqli_real_connect(). Chamá-las após conectar não tem efeito.

Equivalente orientado a objetos

O mesmo programa no estilo OOP — mais claro em bases de código modernas:

<?php
$mysqli = new mysqli();   // unconnected, same as mysqli_init()

$mysqli->options(MYSQLI_INIT_COMMAND, "SET NAMES 'utf8mb4'");
$mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

if (!$mysqli->real_connect("localhost", "username", "password", "database")) {
    echo "Failed to connect: " . $mysqli->connect_error;
    exit;
}

echo "Connected. Server version: " . $mysqli->server_info;
$mysqli->close();
?>

Opções comuns de pré-conexão

Algumas das opções que você normalmente definiria após mysqli_init():

Para TLS, configure com mysqli_ssl_set() (veja mysqli_ssl_set()) antes de mysqli_real_connect().

Armadilhas

• Ela não conecta. Um handle de mysqli_init() não pode ser usado para consultas até que mysqli_real_connect() seja bem-sucedido.
• A ordem importa. Defina todas as opções de pré-conexão antes de conectar, ou elas serão silenciosamente ignoradas.
• Prefira set_charset() para o charset. Usar MYSQLI_INIT_COMMAND com SET NAMES funciona, mas mysqli_set_charset() (chamado após conectar) é a maneira recomendada de definir o charset da conexão, porque a biblioteca cliente também precisa conhecer o charset para escapar corretamente.

Funções relacionadas

• mysqli_real_connect() — abre a conexão em um objeto inicializado.
• mysqli_options() — define as opções de pré-conexão.
• mysqli_connect_errno() / mysqli_connect_error() — inspeciona falhas de conexão.
• Visão geral da extensão mysqli — como todas as peças se encaixam.

Conclusão

mysqli_init() tem um único propósito: obter um objeto MySQLi não conectado para que você possa configurar opções de baixo nível antes do handshake. Se você não precisar dessas opções, new mysqli(...) com credenciais é o caminho mais simples. Recorra a mysqli_init() quando precisar de um timeout de conexão, um init command ou SSL — então mysqli_options() → mysqli_real_connect() completa a sequência.

Prática