init

La función mysqli_init() asigna e inicializa un objeto MySQLi sin abrir una conexión a la base de datos. Es el primer paso de un proceso de conexión en dos fases: se crea el objeto, se ajustan sus opciones de bajo nivel y solo entonces se conecta con mysqli_real_connect(). Esta página explica su sintaxis, valor de retorno, cuándo realmente se necesita y los errores comunes que suelen cometerse.

Sintaxis

mysqli_init(): mysqli|false

En el estilo orientado a objetos no existe un método dedicado — new mysqli() (llamado sin argumentos) realiza la misma inicialización:

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

• Parámetros: ninguno.
• Valor de retorno: un objeto mysqli nuevo y sin conexión en caso de éxito, o false en caso de fallo. (Desde PHP 8.1, la forma procedimental es solo un alias delgado de new mysqli() y lanza una excepción en caso de fallo en lugar de devolver false, en consonancia con la configuración de mysqli_report().)

Por qué existe mysqli_init()

Cuando se llama a new mysqli("localhost", "user", "pass", "db") con argumentos, PHP inicializa el objeto y se conecta en un solo paso. Esto es conveniente, pero no deja margen para configurar opciones que deben establecerse antes del protocolo de enlace (handshake): tiempos de espera de conexión, un comando inicial SET NAMES, SSL o soporte para local-infile.

mysqli_init() separa esas dos fases:

1. Inicializar el objeto con mysqli_init().
2. Configurarlo con mysqli_options() (y SSL mediante mysqli_ssl_set() si es necesario).
3. Conectar con mysqli_real_connect().

Si no se necesitan opciones previas a la conexión, omita mysqli_init() por completo y pase las credenciales directamente a new mysqli() — es más breve e igualmente correcto.

Ejemplo básico

Este es el flujo procedimental canónico. Obsérvese que mysqli_options() se ubica entre init y 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);
?>

El flujo es: crear el objeto, establecer las opciones que deben preceder al protocolo de enlace y luego conectar. Se comprueba el resultado de mysqli_real_connect() y se lee la causa del fallo con mysqli_connect_error(). Finalmente, mysqli_close() libera la conexión.

Importante: las opciones pasadas a mysqli_options() solo tienen efecto si se establecen antes de mysqli_real_connect(). Llamarlas después de conectar no tiene ningún efecto.

Equivalente orientado a objetos

El mismo programa en estilo OOP — más claro en 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();
?>

Opciones comunes previas a la conexión

Algunas de las opciones que normalmente se establecen después de mysqli_init():

Para TLS, configúrelo con mysqli_ssl_set() (véase mysqli_ssl_set()) antes de mysqli_real_connect().

Errores comunes

• No establece la conexión. Un handle de mysqli_init() no puede usarse para consultas hasta que mysqli_real_connect() se complete con éxito.
• El orden importa. Establezca todas las opciones previas a la conexión antes de conectar, o serán ignoradas silenciosamente.
• Prefiera set_charset() para el juego de caracteres. Usar MYSQLI_INIT_COMMAND con SET NAMES funciona, pero mysqli_set_charset() (llamado después de conectar) es la forma recomendada de establecer el juego de caracteres de la conexión, ya que la biblioteca del cliente también necesita conocerlo para escapar correctamente.

Funciones relacionadas

• mysqli_real_connect() — abre la conexión en un objeto inicializado.
• mysqli_options() — establece las opciones previas a la conexión.
• mysqli_connect_errno() / mysqli_connect_error() — inspecciona los fallos de conexión.
• Descripción general de la extensión mysqli — cómo encajan todas las piezas.

Conclusión

mysqli_init() tiene un único propósito: obtener un objeto MySQLi sin conexión para poder configurar opciones de bajo nivel antes del protocolo de enlace. Si no se necesitan esas opciones, new mysqli(...) con credenciales es el camino más sencillo. Recurra a mysqli_init() cuando necesite un tiempo de espera de conexión, un comando de inicialización o SSL — luego mysqli_options() → mysqli_real_connect() completa la secuencia.

Práctica