mysqli_options()

La fonction mysqli_options() définit des options de connexion supplémentaires qui ajustent la façon dont PHP communique avec MySQL. Ce guide explique ce que fait chaque option courante, la règle stricte sur quand vous pouvez l'appeler, et comment la combiner avec mysqli_real_connect() dans une séquence de connexion réelle.

Introduction à la fonction mysqli_options()

mysqli_options() configure le comportement d'un descripteur de connexion MySQLi avant l'ouverture de la connexion. C'est l'équivalent procédural de la méthode orientée objet mysqli::options().

L'essentiel à comprendre est l'ordre des opérations. Un appel normal à mysqli_connect() crée le descripteur et le connecte en une seule étape, ne laissant aucune fenêtre pour définir des options. Pour utiliser mysqli_options(), vous devez séparer ces deux étapes :

1. Créer un descripteur non connecté avec mysqli_init().
2. Définir une ou plusieurs options avec mysqli_options().
3. Ouvrir la connexion réelle avec mysqli_real_connect().

Définir une option après que la connexion est déjà établie n'a soit aucun effet, soit échoue, selon l'option.

Syntaxe

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

• $mysql — un descripteur de connexion retourné par mysqli_init() (pas encore connecté).
• $option — l'une des constantes d'option MYSQLI_* (voir ci-dessous).
• $value — la valeur pour cette option ; le type attendu dépend de l'option.

La fonction retourne true en cas de succès et false en cas d'échec.

Constantes d'option courantes

Comment utiliser la fonction mysqli_options()

L'exemple ci-dessous initialise un descripteur, définit un délai de connexion et active le chargement de fichiers locaux, puis ouvre la connexion :

<?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";
?>

Ici, nous créons d'abord un descripteur non connecté avec mysqli_init(), configurons le délai d'attente et le comportement des fichiers locaux avec mysqli_options(), et seulement ensuite nous connectons avec mysqli_real_connect(). Le résultat de la connexion est vérifié avec mysqli_connect_error(), qui retourne une description de la dernière erreur de connexion.

Exécuter une commande juste après la connexion

MYSQLI_INIT_COMMAND est pratique lorsque chaque connexion doit démarrer dans un état connu — par exemple en forçant un jeu de caractères de session ou un fuseau horaire. L'instruction s'exécute après chaque connexion et reconnexion :

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

Erreurs courantes

• Appelez-la avant de vous connecter. C'est l'erreur la plus fréquente. Utilisez mysqli_init() + mysqli_options() + mysqli_real_connect(), jamais mysqli_connect() seul.
• SSL est séparé. Les chemins vers les certificats, les clés et les CA sont configurés avec mysqli_ssl_set(), pas avec mysqli_options().
• MYSQLI_OPT_LOCAL_INFILE est un paramètre de sécurité. N'activez-le que si vous avez réellement besoin de LOAD DATA LOCAL INFILE ; l'activer peut permettre à un serveur compromis de lire des fichiers locaux.
• Vérifiez la valeur de retour. mysqli_options() retourne false pour les options non supportées, il vaut donc la peine de vérifier quand une option n'a silencieusement aucun effet.

Conclusion

mysqli_options() vous permet d'affiner une connexion MySQLi — délais d'attente, chargement de fichiers locaux et commandes de démarrage — mais uniquement dans la séquence mysqli_init() → mysqli_options() → mysqli_real_connect(). Pour continuer avec les connexions MySQLi, consultez mysqli_connect() et comment diagnostiquer les échecs avec mysqli_connect_error().

Pratique