init

The mysqli_init() function allocates and initializes a MySQLi object without opening a database connection. It is the first step of a two-step connection process: you create the object, tune its low-level options, and only then connect with mysqli_real_connect(). This page explains its syntax, return value, when you actually need it, and the gotchas that trip people up.

Syntax

mysqli_init(): mysqli|false

In object-oriented style there is no dedicated method — new mysqli() (called with no arguments) performs the same initialization:

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

• Parameters: none.
• Return value: a fresh, unconnected mysqli object on success, or false on failure. (Since PHP 8.1 the procedural form is just a thin alias for new mysqli() and throws on failure instead of returning false, in line with mysqli_report() settings.)

Why mysqli_init() exists

When you call new mysqli("localhost", "user", "pass", "db") with arguments, PHP initializes the object and connects in a single step. That is convenient, but it leaves no window to configure options that must be set before the handshake — connection timeouts, an initial SET NAMES command, SSL, or local-infile support.

mysqli_init() splits those two phases apart:

1. Initialize the object with mysqli_init().
2. Configure it with mysqli_options() (and SSL via mysqli_ssl_set() if needed).
3. Connect with mysqli_real_connect().

If you do not need any pre-connection options, skip mysqli_init() entirely and pass credentials straight to new mysqli() — it is shorter and just as correct.

Basic example

This is the canonical procedural workflow. Notice that mysqli_options() sits between init and 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);
?>

The flow is: create the object, set the options that must precede the handshake, then connect. We check the result of mysqli_real_connect() and read the failure reason with mysqli_connect_error(). Finally mysqli_close() releases the connection.

Critical: options passed to mysqli_options() only take effect if they are set before mysqli_real_connect(). Calling them after connecting has no effect.

Object-oriented equivalent

The same program in OOP style — clearer in modern codebases:

<?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();
?>

Common pre-connection options

A few of the options you would typically set after mysqli_init():

For TLS, configure it with mysqli_ssl_set() (see mysqli_ssl_set()) before mysqli_real_connect().

Gotchas

• It does not connect. A handle from mysqli_init() is unusable for queries until mysqli_real_connect() succeeds.
• Order matters. Set every pre-connection option before connecting, or it is silently ignored.
• Prefer set_charset() for the charset. Using MYSQLI_INIT_COMMAND with SET NAMES works, but mysqli_set_charset() (called after connecting) is the recommended way to set the connection charset, because the client library also needs to know the charset for proper escaping.

Related functions

• mysqli_real_connect() — opens the connection on an initialized object.
• mysqli_options() — sets the pre-connection options.
• mysqli_connect_errno() / mysqli_connect_error() — inspect connection failures.
• The mysqli extension overview — how all the pieces fit together.

Conclusion

mysqli_init() is for one job: getting an unconnected MySQLi object so you can configure low-level options before the handshake. If you do not need those options, new mysqli(...) with credentials is the simpler path. Reach for mysqli_init() when you need a connection timeout, an init command, or SSL — then mysqli_options() → mysqli_real_connect() completes the sequence.

Practice