init

La fonction mysqli_init() alloue et initialise un objet MySQLi sans ouvrir de connexion à la base de données. Il s'agit de la première étape d'un processus de connexion en deux phases : vous créez l'objet, configurez ses options de bas niveau, puis vous connectez seulement avec mysqli_real_connect(). Cette page explique sa syntaxe, sa valeur de retour, quand vous en avez réellement besoin, et les pièges courants.

Syntaxe

mysqli_init(): mysqli|false

En style orienté objet, il n'existe pas de méthode dédiée — new mysqli() (appelé sans arguments) effectue la même initialisation :

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

• Paramètres : aucun.
• Valeur de retour : un objet mysqli frais et non connecté en cas de succès, ou false en cas d'échec. (Depuis PHP 8.1, la forme procédurale est simplement un alias léger pour new mysqli() et lève une exception en cas d'échec au lieu de retourner false, conformément aux paramètres de mysqli_report().)

Pourquoi mysqli_init() existe

Lorsque vous appelez new mysqli("localhost", "user", "pass", "db") avec des arguments, PHP initialise l'objet et se connecte en une seule étape. C'est pratique, mais cela ne laisse aucune fenêtre pour configurer des options qui doivent être définies avant la négociation — délais de connexion, une commande SET NAMES initiale, SSL, ou la prise en charge du local-infile.

mysqli_init() sépare ces deux phases :

1. Initialiser l'objet avec mysqli_init().
2. Configurer avec mysqli_options() (et SSL via mysqli_ssl_set() si nécessaire).
3. Connecter avec mysqli_real_connect().

Si vous n'avez pas besoin d'options avant la connexion, ignorez entièrement mysqli_init() et passez les identifiants directement à new mysqli() — c'est plus court et tout aussi correct.

Exemple de base

Voici le flux de travail procédural canonique. Notez que mysqli_options() se trouve entre init et 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);
?>

Le flux est le suivant : créer l'objet, définir les options qui doivent précéder la négociation, puis se connecter. Nous vérifions le résultat de mysqli_real_connect() et lisons la raison de l'échec avec mysqli_connect_error(). Enfin, mysqli_close() libère la connexion.

Important : les options passées à mysqli_options() ne prennent effet que si elles sont définies avant mysqli_real_connect(). Les appeler après la connexion n'a aucun effet.

Équivalent orienté objet

Le même programme en style POO — plus clair dans les bases de code modernes :

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

Options de pré-connexion courantes

Quelques-unes des options que vous configureriez typiquement après mysqli_init() :

Pour TLS, configurez-le avec mysqli_ssl_set() (voir mysqli_ssl_set()) avant mysqli_real_connect().

Pièges courants

• Elle ne connecte pas. Un handle issu de mysqli_init() est inutilisable pour des requêtes tant que mysqli_real_connect() ne réussit pas.
• L'ordre est important. Définissez chaque option avant la connexion, sinon elle est silencieusement ignorée.
• Préférez set_charset() pour le jeu de caractères. Utiliser MYSQLI_INIT_COMMAND avec SET NAMES fonctionne, mais mysqli_set_charset() (appelé après la connexion) est la méthode recommandée pour définir le jeu de caractères de la connexion, car la bibliothèque cliente doit également connaître le jeu de caractères pour un échappement correct.

Fonctions associées

• mysqli_real_connect() — ouvre la connexion sur un objet initialisé.
• mysqli_options() — définit les options de pré-connexion.
• mysqli_connect_errno() / mysqli_connect_error() — inspecter les échecs de connexion.
• La vue d'ensemble de l'extension mysqli — comment toutes les pièces s'assemblent.

Conclusion

mysqli_init() n'a qu'un seul rôle : obtenir un objet MySQLi non connecté afin que vous puissiez configurer des options de bas niveau avant la négociation. Si vous n'avez pas besoin de ces options, new mysqli(...) avec les identifiants est la voie la plus simple. Utilisez mysqli_init() lorsque vous avez besoin d'un délai de connexion, d'une commande d'initialisation, ou de SSL — puis mysqli_options() → mysqli_real_connect() complète la séquence.

Pratique