mysqli_options()

A função mysqli_options() define opções de conexão extras que ajustam como o PHP se comunica com o MySQL. Este guia explica o que cada opção comum faz, a regra estrita sobre quando você pode chamá-la e como combiná-la com mysqli_real_connect() em uma sequência de conexão real.

Introdução à função mysqli_options()

mysqli_options() configura o comportamento de um identificador de conexão MySQLi antes de a conexão ser aberta. É o equivalente procedural do método orientado a objetos mysqli::options().

O ponto essencial é entender a ordem das operações. Uma chamada normal a mysqli_connect() tanto cria o identificador quanto conecta em um único passo, sem janela para definir opções. Para usar mysqli_options(), você precisa separar esses dois passos:

1. Crie um identificador não conectado com mysqli_init().
2. Defina uma ou mais opções com mysqli_options().
3. Abra a conexão real com mysqli_real_connect().

Definir uma opção após a conexão já estar estabelecida não tem efeito ou falha, dependendo da opção.

Sintaxe

mysqli_options(mysqli $mysql, int $option, mixed $value): bool

• $mysql — um identificador de conexão retornado por mysqli_init() (ainda não conectado).
• $option — uma das constantes de opção MYSQLI_* (veja abaixo).
• $value — o valor para essa opção; o tipo esperado depende da opção.

A função retorna true em caso de sucesso e false em caso de falha.

Constantes de opção comuns

Como usar a função mysqli_options()

O exemplo abaixo inicializa um identificador, define um timeout de conexão e ativa o carregamento de arquivos locais, e então abre a conexão:

<?php
$mysqli = mysqli_init();

/* Set connection timeout to 10 seconds */
mysqli_options($mysqli, MYSQLI_OPT_CONNECT_TIMEOUT, 10);

/* Enable LOAD DATA LOCAL INFILE */
mysqli_options($mysqli, MYSQLI_OPT_LOCAL_INFILE, 1);

/* Now open the actual connection */
if (!mysqli_real_connect($mysqli, "localhost", "username", "password", "database")) {
    die("Connection failed: " . mysqli_connect_error());
}

echo "Connected successfully";
?>

Aqui primeiro criamos um identificador não conectado com mysqli_init(), configuramos o timeout e o comportamento de arquivo local com mysqli_options(), e somente então conectamos com mysqli_real_connect(). O resultado da conexão é verificado com mysqli_connect_error(), que retorna uma descrição da última falha de conexão.

Executando um comando logo após conectar

MYSQLI_INIT_COMMAND é útil quando toda conexão deve começar em um estado conhecido — por exemplo, forçando um conjunto de caracteres de sessão ou fuso horário. A instrução é executada após cada conexão e reconexão:

<?php
$mysqli = mysqli_init();

mysqli_options($mysqli, MYSQLI_INIT_COMMAND, "SET NAMES 'utf8mb4'");

if (!mysqli_real_connect($mysqli, "localhost", "username", "password", "database")) {
    die("Connection failed: " . mysqli_connect_error());
}
?>

Erros comuns

• Chame-a antes de conectar. Este é o erro mais frequente. Use mysqli_init() + mysqli_options() + mysqli_real_connect(), nunca o simples mysqli_connect().
• SSL é separado. Caminhos de certificado, chave e CA são configurados com mysqli_ssl_set(), não com mysqli_options().
• MYSQLI_OPT_LOCAL_INFILE é uma configuração de segurança. Ative-a somente se você realmente precisar de LOAD DATA LOCAL INFILE; ativá-la pode permitir que um servidor comprometido leia arquivos locais.
• Verifique o valor de retorno. mysqli_options() retorna false para opções não suportadas, portanto vale a pena verificar quando uma opção não tem efeito silenciosamente.

Conclusão

mysqli_options() permite ajustar com precisão uma conexão MySQLi — timeouts, carregamento de arquivos locais e comandos de inicialização — mas somente dentro da sequência mysqli_init() → mysqli_options() → mysqli_real_connect(). Para continuar com conexões MySQLi, veja mysqli_connect() e como diagnosticar falhas com mysqli_connect_error().

Prática