real_connect

Dans cet article, nous allons aborder la méthode real_connect() en PHP, utilisée pour établir une connexion à une base de données MySQL. (L'équivalent procédural est mysqli_real_connect().)

Cette page explique ce qui distingue real_connect() d'un simple mysqli_connect(), la liste complète des paramètres, la manière d'activer SSL et d'autres indicateurs de connexion, ainsi que les problèmes les plus courants.

Qu'est-ce que real_connect() et pourquoi l'utiliser ?

La méthode real_connect() ouvre une connexion à un serveur MySQL, tout comme mysqli_connect(). La différence essentielle est que real_connect() opère sur un handle de connexion que vous avez déjà créé avec mysqli_init(), au lieu de créer et de se connecter en une seule étape.

Cette étape supplémentaire est importante car elle vous offre une fenêtre entre la création du handle et la connexion, durant laquelle vous pouvez configurer des options qui ne peuvent être définies qu'avant l'établissement de la connexion. Utilisez real_connect() (plutôt que mysqli_connect()) lorsque vous avez besoin de :

• Définir des options de connexion avec mysqli_options() — par exemple un délai de connexion (MYSQLI_OPT_CONNECT_TIMEOUT) ou la prise en charge de fichiers locaux.
• Activer une connexion SSL/TLS avec ssl_set() et l'indicateur MYSQLI_CLIENT_SSL.
• Passer des indicateurs client tels que MYSQLI_CLIENT_COMPRESS ou MYSQLI_CLIENT_FOUND_ROWS.
• Ouvrir une connexion persistante en préfixant l'hôte avec p:.

Si vous n'avez besoin d'aucune de ces fonctionnalités, le plus simple mysqli_connect() convient parfaitement.

Utilisation de base

real_connect() suit toujours un modèle en deux étapes : créer le handle, puis se connecter. Voici l'approche orientée objet :

<?php
$mysqli = mysqli_init();

if (!$mysqli) {
    die('mysqli_init failed');
}

if (!$mysqli->real_connect('localhost', 'username', 'password', 'database')) {
    die('Connect Error (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error);
}

echo 'Success... ' . $mysqli->host_info . "\n";

$mysqli->close();
?>

Nous créons d'abord un handle MySQLi avec mysqli_init() et vérifions qu'il a réussi. Nous appelons ensuite real_connect() sur l'objet $mysqli pour nous connecter. En cas d'échec, nous signalons l'erreur avec connect_errno et connect_error et nous arrêtons ; en cas de succès, nous affichons les informations d'hôte et libérons enfin la connexion avec close().

Paramètres

real_connect() accepte les paramètres suivants, tous optionnels, dans cet ordre :

Remarque : avec l'API OO, le handle est l'objet, donc le premier argument est host. Avec le procédural mysqli_real_connect($link, $host, ...), le lien est passé en premier.

Définir des options avant la connexion

C'est la raison principale pour laquelle real_connect() existe. Configurez le handle avec mysqli_options() entre init et real_connect :

<?php
$mysqli = mysqli_init();

// These can only be set before connecting:
$mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);
$mysqli->options(MYSQLI_INIT_COMMAND, "SET autocommit = 0");

if (!$mysqli->real_connect('localhost', 'username', 'password', 'database')) {
    die('Connect Error (' . $mysqli->connect_errno . ') ' . $mysqli->connect_error);
}

echo 'Connected with a 5-second timeout.';
$mysqli->close();
?>

Connexion avec SSL et indicateurs client

Le septième paramètre est un masque de bits d'indicateurs client. Pour exiger une connexion chiffrée, configurez les certificats avec ssl_set() et passez MYSQLI_CLIENT_SSL :

<?php
$mysqli = mysqli_init();

$mysqli->ssl_set(null, null, '/path/to/ca-cert.pem', null, null);

$mysqli->real_connect(
    'db.example.com', 'username', 'password', 'database',
    3306, null,
    MYSQLI_CLIENT_SSL
);

echo 'Encrypted connection established.';
$mysqli->close();
?>

Indicateurs courants que vous pouvez combiner avec | :

• MYSQLI_CLIENT_SSL — utiliser le chiffrement SSL/TLS.
• MYSQLI_CLIENT_COMPRESS — utiliser le protocole compressé.
• MYSQLI_CLIENT_FOUND_ROWS — retourner les lignes correspondantes au lieu des lignes modifiées.

Connexions persistantes

Préfixer l'hôte avec p: réutilise une connexion existante du pool entre les requêtes au lieu d'en ouvrir une nouvelle à chaque fois, ce qui peut réduire la surcharge de connexion sur les serveurs très sollicités :

<?php
$mysqli = mysqli_init();
$mysqli->real_connect('p:localhost', 'username', 'password', 'database');
?>

Problèmes courants

• Oublier mysqli_init(). real_connect() doit être appelé sur un handle retourné par mysqli_init(). L'appeler sur un new mysqli() fraîchement construit et déjà connecté échouera.
• Vérifier la mauvaise propriété d'erreur. Avant qu'une connexion existe, utilisez connect_errno / connect_error, et non errno / error.
• Définir les options trop tard. Des options comme le délai de connexion n'ont aucun effet une fois la connexion ouverte — elles doivent être définies avant real_connect().

Conclusion

La méthode real_connect() établit une connexion MySQL à partir d'un handle créé avec mysqli_init(), vous donnant la possibilité de configurer des délais d'attente, SSL et des indicateurs client qu'un mysqli_connect() en une seule étape ne peut pas gérer. Une fois connecté, vous pouvez exécuter des instructions avec query() et sélectionner une base de données avec select_db().

Pratique