quickstart.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 60a292997b3c6341cf52099d901aa0b5f8673d87 Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->

<chapter xml:id="mysqli.quickstart" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Guide de démarrage rapide</title>
 <para>
  Ce guide de démarrage rapide va vous aider à vous familiariser
  avec l'API PHP MySQL.
 </para>
 <para>
  Il fournit une vue d'ensemble de l'extension mysqli. Des exemples de code
  sont fournis pour tous les aspects importants de l'API. Les concepts
  de base de données sont expliqués avec une finesse permettant de
  comprendre les spécificités des concepts de MySQL.
 </para>
 <para>
  Requis : Vous devez être familier avec le langage de programmation PHP,
  le langage SQL ainsi qu'avoir quelques bases avec le serveur MySQL.
 </para>
 <section xml:id="mysqli.quickstart.dual-interface">
  <title>Interface procédurale et orientée objet</title>
  <para>
   L'extension mysqli fournit 2 interfaces. Elle supporte la programmation
   procédurale mais aussi, la programmation orientée objet.
  </para>
  <para>
   Les utilisateurs migrants depuis l'ancienne extension mysql préfèreront
   l'interface procédurale. Cette interface est similaire à celle utilisée
   par l'ancienne extension mysql. Dans la plupart des cas, les noms de fonctions
   ne diffèrent que par leurs préfixes. Quelques fonctions mysqli prennent
   un gestionnaire de connexion comme premier argument, alors que la fonction
   correspondante de l'ancienne interface mysql le prenait comme argument
   optionnel en dernière position.
  </para>
  <para>
   <example>
    <title>Migration facile depuis l'ancienne extension mysql</title>
    <programlisting role="php">
<![CDATA[
<?php

$mysqli = mysqli_connect("example.com", "user", "password", "database");
$result = mysqli_query($mysqli, "SELECT 'Please do not use the deprecated mysql extension for new development. ' AS _msg FROM DUAL");
$row = mysqli_fetch_assoc($result);
echo $row['_msg'];

$mysql = mysql_connect("example.com", "user", "password"); 
mysql_select_db("test");
$result = mysql_query("SELECT 'Use the mysqli extension instead.' AS _msg FROM DUAL", $mysql);
$row = mysql_fetch_assoc($result);
echo $row['_msg'];
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Please do not use the deprecated mysql extension for new development. Use the mysqli extension instead.
]]>
    </screen>
   </example>
  </para>
  <para>
   <emphasis role="bold">L'interface orientée objet</emphasis>
  </para>
  <para>
   En plus de l'interface procédurale, les utilisateurs peuvent choisir
   d'utiliser l'interface orientée objet. La documentation est organisée
   en utilisant cette interface. Elle montre les fonctions groupées
   par leurs buts, rendant simple le démarrage de la programmation.
   La section référence fournit des exemples sur les deux syntaxes.
  </para>
  <para>
   Il n'y a pas de différence significative d'un point de vue performance
   entre les deux interfaces. Les utilisateurs peuvent faire leur choix
   que d'un point de vue personnel.
  </para>
  <para>
   <example>
    <title>Interface procédurale et orientée objet</title>
    <programlisting role="php">
<![CDATA[
<?php

$mysqli = mysqli_connect("example.com", "user", "password", "database");
$result = mysqli_query($mysqli, "SELECT 'A world full of ' AS _msg FROM DUAL");
$row = mysqli_fetch_assoc($result);
echo $row['_msg'];

$mysqli = new mysqli("example.com", "user", "password", "database");
$result = $mysqli->query("SELECT 'choices to please everybody.' AS _msg FROM DUAL");
$row = $result->fetch_assoc();
echo $row['_msg'];
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
A world full of choices to please everybody.
]]>
    </screen>
   </example>
  </para>
  <para>
   L'interface orientée objet est utilisée dans le démarrage rapide de la documentation
   en raison du fait que la section référence est organisée de cette façon.
  </para>
  <para>
   <emphasis role="bold">Mixage des styles</emphasis>
  </para>
  <para>
   Il est possible de passer d'un style à un autre à tout moment bien que ce ne
   soit pas recommandé pour des raisons de clarté et de style de codage.
  </para>
  <para>
   <example>
    <title>Mauvais style de codage</title>
    <programlisting role="php">
<![CDATA[
<?php

$mysqli = new mysqli("example.com", "user", "password", "database");
$result = mysqli_query($mysqli, "SELECT 'Possible but bad style.' AS _msg FROM DUAL");

if ($row = $result->fetch_assoc()) {
    echo $row['_msg'];
}
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Possible but bad style.
]]>
    </screen>
    </example>
  </para>
  <para>
   <emphasis role="bold">Voir aussi</emphasis>
  </para>
  <para>
   <simplelist>
    <member><methodname>mysqli::__construct</methodname></member>
    <member><methodname>mysqli::query</methodname></member>
    <member><methodname>mysqli_result::fetch_assoc</methodname></member>
    <member><link linkend="mysqli.connect-errno">$mysqli::connect_errno</link></member>
    <member><link linkend="mysqli.connect-error">$mysqli::connect_error</link></member>
    <member><link linkend="mysqli.errno">$mysqli::errno</link></member>
    <member><link linkend="mysqli.error">$mysqli::error</link></member>
    <member><link linkend="mysqli.summary">Le résumé des fonctions de l'extension MySQLi</link></member>
   </simplelist>
  </para>
 </section>
 
 <section xml:id="mysqli.quickstart.connections">
  <title>Connexions</title>
  <para>
   Le serveur MySQL supporte l'utilisation de différentes couches de transport
   pour les connexions. Les connexions peuvent utiliser TCP/IP, les sockets
   de domaine Unix ou les pipes nommés Windows.
  </para>
  <para>
   Le nom d'hôte <literal>localhost</literal> a une signification particulière.
   Il est lié à l'utilisation des sockets de domaine Unix. 
   Pour ouvrir une connexion TCP/IP sur l'hôte local, <literal>127.0.0.1</literal> doit être utilisé
   au lieu de <literal>localhost</literal>.
  </para>
  <para>
   <example>
    <title>Signification spéciale de localhost</title>
    <programlisting role="php">
<![CDATA[
<?php

$mysqli = new mysqli("localhost", "user", "password", "database");

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

$mysqli = new mysqli("127.0.0.1", "user", "password", "database", 3306);

echo $mysqli->host_info . "\n";
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Localhost via UNIX socket
127.0.0.1 via TCP/IP
]]>
    </screen>
   </example>
  </para>
  <para>
   <emphasis role="bold">Paramètres par défaut d'une connexion</emphasis>
  </para>
  <para>
   Suivant la fonction de connexion utilisée, des paramètres peuvent être omis.
   Si un paramètre n'est pas fourni, alors l'extension tentera d'utiliser les valeurs
   par défaut définies dans le fichier de configuration de PHP.
  </para>
  <para>
   <example>
    <title>Paramètres par défaut</title>
    <programlisting role="ini">
<![CDATA[
mysqli.default_host=192.168.2.27
mysqli.default_user=root
mysqli.default_pw=""
mysqli.default_port=3306
mysqli.default_socket=/tmp/mysql.sock
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Ces valeurs de paramètres sont alors passées à la bibliothèque cliente
   utilisée par l'extension. Si la bibliothèque cliente détecte un paramètre
   vide ou non défini, alors elle utilisera les valeurs par défaut internes à
   la bibliothèque.
  </para>
  <para>
   <emphasis role="bold">Valeurs par défaut internes à la bibliothèque pour la connexion</emphasis>
  </para>
  <para>
   Si la valeur de l'hôte n'est pas définie ou est vide, alors la bibliothèque cliente
   utilisera par défaut une connexion de type socket Unix sur <literal>localhost</literal>.
   Si le socket n'est pas défini ou vide, et qu'une connexion de type socket Unix est
   demandée, alors une connexion au socket par défaut <literal>/tmp/mysql.sock</literal>
   sera tentée.
  </para>
  <para>
   Sous les systèmes Windows, le nom d'hôte <literal>.</literal> est interprété
   par la bibliothèque cliente comme une tentative d'ouvrir un tube nommé Windows
   pour la connexion. Dans ce cas, le paramètre socket est interprété comme
   un tube nommé. S'il n'est pas fourni ou vide, alors le socket (tube nommé)
   vaudra par défaut <literal>\\.\pipe\MySQL</literal>.
  </para>
  <para>
   Si ni un socket de domaine Unix, ni un tube nommé Windows n'est fourni, une connexion
   de base sera établie et si la valeur du port n'est pas défini, la bibliothèque
   utilisera le port <literal>3306</literal>.
  </para>
  <para>
   La bibliothèque <link linkend="mysqlnd.overview">mysqlnd</link> et la bibliothèque
   cliente MySQL (libmysqlclient) implémentent la même logique pour déterminer les valeurs
   par défaut.
  </para>
  <para>
   <emphasis role="bold">Options de connexion</emphasis>
  </para>
  <para>
   Des options de connexion sont disponibles pour, par exemple, définir
   des commandes d'initialisation à exécuter lors de la connexion, ou
   pour demander l'utilisation d'un jeu de caractères particulier. Les options
   de connexion doivent être définies avant la connexion au réseau.
  </para>
  <para>
   Pour définir une option de connexion, l'opération de connexion doit
   être effectuée en 3 étapes : création d'un gestionnaire de connexion avec
   <function>mysqli_init</function> ou <methodname>mysqli::__construct</methodname>, 
   définition des options demandées en utilisant
   <methodname>mysqli::options</methodname>, et connexion au réseau avec
   <methodname>mysqli::real_connect</methodname>.
  </para>
  <para>
   <emphasis role="bold">File d'attente de connexion</emphasis>
  </para>
  <para>
   L'extension mysqli supporte les connexions persistantes au base de données,
   qui sont des connexions spéciales. Par défaut, chaque connexion à une
   base de données ouverte par un script est soit explicitement close par
   l'utilisateur durant l'exécution, ou soit libérée automatiquement à la fin
   du script. Ce n'est pas le cas d'une connexion persistante. En effet,
   elle sera placée dans une file d'attente pour une ré-utilisation future,
   si une connexion au même serveur, utilisant le même nom d'utilisateur, le
   même mot de passe, le même socket, le même port, ainsi que la même base de données
   est ouverte. Cette ré-utilisation permet d'alléger la charge indue par les
   connexions.
  </para>
  <para>
   Chaque processus PHP utilise sa propre file d'attente de connexions mysqli.
   Suivant le modèle de déploiement du serveur web, un processus PHP peut
   servir une ou plusieurs requêtes. Toutefois, une connexion mise en file d'attente
   peut être utilisée par un ou plusieurs scripts par la suite.
  </para>
  <para>
   <emphasis role="bold">Les connexions persistantes</emphasis>
  </para>
  <para>
   Si une connexion persistante pour une combinaison d'hôte, de nom d'utilisateur,
   de mot de passe, de socket, de port et de base de données inutilisée ne peut
   être trouvée dans la file d'attente de connexion, alors mysqli ouvrira une nouvelle
   connexion. L'utilisation des connexions persistantes peut être activée ou désactivée
   en utilisant la directive PHP
   <link linkend="ini.mysqli.allow-persistent">mysqli.allow_persistent</link>.
   Le nombre total de connexions ouvertes par un script peut être limité avec
   la directive <link linkend="ini.mysqli.max-links">mysqli.max_links</link>.
   Le nombre maximal de connexions persistantes par processus PHP peut être
   restreint avec la directive <link linkend="ini.mysqli.max-persistent">mysqli.max_persistent</link>.
   Veuillez noter que le serveur web peut engendrer plusieurs processus PHP.
  </para>
  <para>
   Une plainte courante contre les connexions persistantes est que leurs
   statuts n'est pas ré-initialisés avant la ré-utilisation. Par exemple,
   les transactions ouvertes et non terminées ne sont pas automatiquement
   annulées. Mais aussi, les modifications autorisées survenant entre le moment
   où la connexion est mise en file d'attente et sa ré-utilisation ne seront
   pas prises en compte. Ce comportement peut être vu comme un effet de
   bord non désiré. Au contraire, le nom <literal>persistent</literal>
   peut être compris comme une promesse sur le fait que le statut persiste
   réellement.
  </para>
  <para>
   L'extension mysqli supporte deux interprétations d'une connexion persistante :
   statut persistant, et un statut réinitialisé avant ré-utilisation. Par
   défaut, il sera réinitialisé. Avant qu'une connexion persistante ne soit
   réutilisée, l'extension mysqli appelle implicitement la fonction
   <methodname>mysqli::change_user</methodname> pour réinitialiser le statut.
   La connexion persistante apparaît à l'utilisateur comme si elle venait
   juste d'être ouverte. Aucune trace d'une utilisation précédente ne
   sera visible.
  </para>
  <para>
   La fonction <methodname>mysqli::change_user</methodname> est une opération couteuse.
   Pour de meilleures performances, les utilisateurs peuvent vouloir re-compiler
   l'extension avec le drapeau de compilation <constant>MYSQLI_NO_CHANGE_USER_ON_PCONNECT</constant>.
  </para>
  <para>
   Ainsi, il sera laissé à l'utilisateur le choix entre un comportement sécurisé
   et une performance optimisée. Les deux ont comme but l'optimisation. Pour
   une utilisation plus simple, le comportement sécurisé a été placé
   par défaut au détriment d'une performance maximale.
  </para>
  <para>
   <emphasis role="bold">Voir aussi</emphasis>
  </para>
  <para>
   <simplelist>
    <member><function>mysqli_init</function></member>
    <member><methodname>mysqli::__construct</methodname></member>
    <member><methodname>mysqli::options</methodname></member>
    <member><methodname>mysqli::real_connect</methodname></member>
    <member><methodname>mysqli::change_user</methodname></member>
    <member><link linkend="mysqli.get-host-info">$mysqli::host_info</link></member>
    <member><link linkend="mysqli.configuration">Les options de configuration MySQLi</link></member>
    <member><link linkend="features.persistent-connections">Les connexions persistantes aux bases de données</link></member>
   </simplelist>
  </para>
 </section>
 <section xml:id="mysqli.quickstart.statements">
  <title>Exécution des requêtes</title>
  <para>
   Les requêtes peuvent être exécutées avec les fonctions
   <methodname>mysqli::query</methodname>, <methodname>mysqli::real_query</methodname>
   et <methodname>mysqli::multi_query</methodname>.. La fonction
   <methodname>mysqli::query</methodname> est la plus commune, et combine
   l'exécution de la requête avec une récupération
   de son jeu de résultats en mémoire tampon, s'il y en a un, en un seul appel.
   Appeler la fonction <methodname>mysqli::query</methodname>
   est identique à appeler la fonction
   <methodname>mysqli::real_query</methodname>suivie d'un appel à la fonction
   <methodname>mysqli::store_result</methodname>.
  </para>
  <para>
   <example>
    <title>Exécution des requêtes</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <emphasis role="bold">Jeux de résultats en mémoire tampon</emphasis>
  </para>
  <para>
   Après exécution de la requête, les résultats peuvent être intégralement récupérés
   en une fois ou bien être lus ligne par ligne. La mise en mémoire 
   tampon du jeu de résultats côté client autorise le serveur à libérer
   les ressources associées avec le résultat de la requête aussi vite que possible. 
   De manière générale, les clients sont lents à parcourir les jeux de résultats. 
   Toutefois, il est recommandéd'utiliser la mise en mémoire tampon des 
   jeux de résultats. La fonction <methodname>mysqli::query</methodname> 
   combine à la fois l'exécution de la requête et la mise en mémoire tampon du jeu de résultats.
  </para>
  <para>
   Les applications PHP peuvent naviguer librement dans les résultats
   mis en mémoire tampon. La navigation est rapide car les jeux de résultats
   sont stockés dans la mémoire client. Veuillez garder à l'esprit qu'il
   est souvent plus simple de réaliser cette opération par le client que
   par le serveur.
  </para>
  <para>
   <example>
    <title>Navigation dans des résultats mis en mémoire tampon</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

$result = $mysqli->query("SELECT id FROM test ORDER BY id ASC");

echo "Ordre inversé...\n";
for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
    $result->data_seek($row_no);
    $row = $result->fetch_assoc();
    echo " id = " . $row['id'] . "\n";
}

echo "Ordre du jeu de résultats...\n";
foreach ($result as $row) {
    echo " id = " . $row['id'] . "\n";
}
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Ordre inversé...
 id = 3
 id = 2
 id = 1
Ordre du jeu de résultats...
 id = 1
 id = 2
 id = 3
]]>
    </screen>
   </example>
  </para>
  <para>
   <emphasis role="bold">Jeux de résultats non mis en mémoire tampon</emphasis>
  </para>
  <para>
   Si la mémoire client est une ressource limitée, et que la libération
   des ressources serveur aussi vite que possible pour conserver une charge
   serveur basse n'est pas nécessaire, les résultats non mis en mémoire tampon
   peuvent être utilisés. La navigation au travers de résultats non mis en mémoire
   tampon n'est pas possible tant que toutes les lignes n'ont pas été lues.
  </para>
  <para>
   <example>
    <title>Navigation dans des résultats non mis en mémoire tampon</title>
    <programlisting role="php">
<![CDATA[
<?php

$mysqli->real_query("SELECT id FROM test ORDER BY id ASC");
$result = $mysqli->use_result();

echo "Ordre du jeu de résultats...\n";
foreach ($result as $row) {
    echo " id = " . $row['id'] . "\n";
}
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <emphasis role="bold">Types de données des valeurs du jeu de résultats</emphasis>
  </para>
  <para>
   Les fonctions <methodname>mysqli::query</methodname>, <methodname>mysqli::real_query</methodname>
   et <methodname>mysqli::multi_query</methodname> sont utilisées pour exécuter des
   requêtes non-préparées. Au niveau du protocole client-serveur MySQL, la commande
   <literal>COM_QUERY</literal> ainsi que le protocole texte sont utilisés pour
   l'exécution de la requête. Avec le protocole texte, le serveur MySQL convertit
   toutes les données d'un jeu de résultats en chaînes de caractères avant de les envoyer.
   La bibliothèque cliente mysql reçoit toutes les valeurs des colonnes sous forme
   de chaîne de caractères. Aucun autre transtypage côté client n'est effectué
   pour retrouver le type natif des colonnes. A la place de cela, toutes les valeurs sont
   fournis sous la forme de chaîne de caractères PHP.
  </para>
  <para>
   <example>
    <title>Le protocole texte retourne des chaînes de caractères par défaut</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label CHAR(1))");
$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')");

$result = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
$row = $result->fetch_assoc();

printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
printf("label = %s (%s)\n", $row['label'], gettype($row['label']));
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
id = 1 (string)
label = a (string)
]]>
    </screen>
   </example>
  </para>
  <para>
   Il est possible de convertir des colonnes de type entières et nombres à virgule flottante
   en nombre PHP en définissant l'option de connexion
   <constant>MYSQLI_OPT_INT_AND_FLOAT_NATIVE</constant>, si vous utilisez la bibliothèque
   mysqlnd. Si défini, la bibliothèque mysqlnd va vérifier les méta-données des types
   des colonnes dans le jeu de résultats et va convertir les colonnes SQL numériques
   en nombres PHP, si la valeur entre dans l'intervalle autorisé de PHP.
   De cette façon, par exemple, les colonnes SQL INT sont retournées sous la forme
   d'entier.
  </para>
  <para>
   <example>
    <title>Types natifs des données avec mysqlnd et l'option de connexion</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
 
$mysqli = new mysqli();
$mysqli->options(MYSQLI_OPT_INT_AND_FLOAT_NATIVE, 1);
$mysqli->real_connect("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label CHAR(1))");
$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'a')");

$result = $mysqli->query("SELECT id, label FROM test WHERE id = 1");
$row = $result->fetch_assoc();

printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
printf("label = %s (%s)\n", $row['label'], gettype($row['label']));
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
id = 1 (integer)
label = a (string)
]]>
    </screen>
   </example>
  </para>
  <para>
   <emphasis role="bold">Voir aussi</emphasis>
  </para>
  <para>
   <simplelist>
    <member><methodname>mysqli::__construct</methodname></member>
    <member><methodname>mysqli::options</methodname></member>
    <member><methodname>mysqli::real_connect</methodname></member>
    <member><methodname>mysqli::query</methodname></member>
    <member><methodname>mysqli::multi_query</methodname></member>
    <member><methodname>mysqli::use_result</methodname></member>
    <member><methodname>mysqli::store_result</methodname></member>
   </simplelist>
  </para>
 </section>

 <section xml:id="mysqli.quickstart.prepared-statements">
  <title>Les requêtes préparées</title>
  <para>
   La base de données MySQL supporte les requêtes préparées. Une requête
   préparée ou requête paramétrable est utilisée pour exécuter la
   même requête plusieurs fois, avec une grande efficacité et protège 
   des injections SQL.
  </para>
  <para>
   <emphasis role="bold">Flux de travail de base</emphasis>
  </para>
  <para>
   L'exécution d'une requête préparée se déroule en deux étapes :
   la préparation et l'exécution. Lors de la préparation, un template
   de requête est envoyé au serveur de base de données. Le serveur effectue
   une vérification de la syntaxe, et initialise les ressources internes
   du serveur pour une utilisation ultérieure.
  </para>
  <para>
   Le serveur MySQL supporte le mode anonyme, avec des marqueurs de position
   utilisant le caractère <literal>?</literal>.
  </para>
    <para>
    La préparation est suivie de l'exécution. Pendant l'exécution, le client lie
    les valeurs des paramètres et les envoie au serveur. Le serveur exécute
    l'instruction avec les valeurs liées en utilisant les ressources internes 
    précédemment créées.
  </para>
  <para>
   <example>
    <title>Première étape : la préparation</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

// Requête non préparée
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label TEXT)");

// Requête préparée, étape 1 : préparation
$stmt = $mysqli->prepare("INSERT INTO test(id, label) VALUES (?, ?)");

// Requête préparée, étape 2 : lie les valeurs et exécute la requête
$id = 1;
$label = 'PHP';
$stmt->bind_param("is", $id, $label); // "is" means that $id is bound as an integer and $label as a string

$stmt->execute();
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <emphasis role="bold">Exécution répétée</emphasis>
  </para>
  <para>
   Une requête préparée peut être exécutée à plusieurs reprises. A chaque
   exécution, la valeur courante de la variable liée est évaluée, et envoyée
   au serveur. La requête n'est pas analysée de nouveau. Le template de requête
   n'est pas une nouvelle fois envoyée au serveur non plus.
  </para>
  <para>
   <example>
    <title>Requête de type INSERT préparée une seule fois, et exécutée plusieurs fois</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

// Requête non préparée
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label TEXT)");

// Requête préparée, étape 1 : la préparation
if (!($stmt = $mysqli->prepare("INSERT INTO test(id) VALUES (?)"))) {
     echo "Échec lors de la préparation : (" . $mysqli->errno . ") " . $mysqli->error;
}

// Requête préparée, étape 2 : lie les valeurs et exécute la requête
$id = 1;
$stmt->bind_param("is", $id, $label); // "is" means that $id is bound as an integer and $label as a string

$data = [
    1 => 'PHP',
    2 => 'Java',
    3 => 'C++'
];

foreach ($data as $id => $label) {
    $stmt->execute();
}

$result = $mysqli->query('SELECT id, label FROM test');
var_dump($result->fetch_all(MYSQLI_ASSOC));
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(3) {
  array(2) {
    ["id"]=>
    string(1) "1"
    ["label"]=>
    string(3) "PHP"
  }
  [1]=>
  array(2) {
    ["id"]=>
    string(1) "2"
    ["label"]=>
    string(4) "Java"
  }
  [2]=>
  array(2) {
    ["id"]=>
    string(1) "3"
    ["label"]=>
    string(3) "C++"
  }
}
]]>
    </screen>
   </example>
  </para>
  <para>
   Chaque requête préparée occupe des ressources sur le serveur. Elles doivent
   être fermées explicitement immédiatement après utilisation. Si vous ne
   le faîtes pas, la requête sera fermée lorsque le gestionnaire de requête
   sera libéré par PHP.
  </para>
  <para>
   L'utilisation de requête préparée n'est pas toujours la façon la plus
   efficace d'exécuter une requête. Une requête préparée exécutée une seule
   fois provoque plus d'aller-retour client-serveur qu'une requête non préparée.
   C'est pour cela que la requête de type <literal>SELECT</literal>
   n'est pas exécutée comme requête préparée dans l'exemple ci-dessus.
  </para>
  <para>
   De plus, vous devez prendre en considération l'utilisation des syntaxes
   multi-INSERT MySQL pour les INSERTs. Par exemple, les multi-INSERTs requièrent
   moins d'aller-retour client-serveur que la requête préparée vue dans l'exemple ci-dessus.
  </para>
  <para>
   <example>
    <title>Moins d'aller-retour en utilisant les multi-INSERTs SQL</title>
    <programlisting role="php">
<![CDATA[
<?php
 
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");
 
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
 
$values = [1, 2, 3, 4];
 
$stmt = $mysqli->prepare("INSERT INTO test(id) VALUES (?), (?), (?), (?)");
$stmt->bind_param('iiii', ...$values);
$stmt->execute();
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <emphasis role="bold">Types de données des valeurs du jeu de résultats</emphasis>
  </para>
  <para>
   Le protocole serveur client MySQL définit un protocole de transfert des données
   différent pour les requêtes préparées et pour les requêtes non préparées.
   Les requêtes préparées utilisent un protocole appelé binaire. Le serveur MySQL
   envoie les données du jeu de résultats "tel que", au format binaire. Les résultats
   ne sont pas sérialisés en chaînes de caractères avant envoi. La bibliothèque cliente
   reçoit des données binaires et tente de convertir les valeurs en un type de données
   PHP approprié. Par exemple, les résultats depuis une colonne <literal>INT</literal>
   SQL seront fournis comme variables de type entier PHP.
  </para>
  <para>
   <example>
    <title>Types de données natifs</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

// Requête non préparée
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label TEXT)");
$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

$stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
$stmt->execute();
$result = $stmt->get_result();
$row = $result->fetch_assoc();

printf("id = %s (%s)\n", $row['id'], gettype($row['id']));
printf("label = %s (%s)\n", $row['label'], gettype($row['label']));
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
id = 1 (integer)
label = PHP (string)
]]>
    </screen>
   </example>
  </para>
  <para>
   Ce comportement diffère pour les requêtes non préparées. Par défaut, les
   requêtes non préparées retournent tous les résultats sous forme de chaînes
   de caractères. Ce comportement par défaut peut être modifié en utilisant
   une option lors de la connexion. Si cette option est utilisée,
   alors il n'y aura plus de différence entre une requête préparée et une
   requête non préparée.
  </para>
  <para>
   <emphasis role="bold">Récupération des résultats en utilisant des variables liées</emphasis>
  </para>
  <para>
   Les résultats depuis les requêtes préparées peuvent être récupérées
   en liant les variables de sortie, ou en interrogeant l'objet
   <classname>mysqli_result</classname>.
  </para>
  <para>
   Les variables de sortie doivent être liées après l'exécution de la requête.
   Une variable doit être liée pour chaque colonne du jeu de résultats de la requête.
  </para>
  <para>
   <example>
    <title>Liage des variables de sortie</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

// Requête non préparée
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label TEXT)");
$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

$stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
$stmt->execute();

$stmt->bind_result($out_id, $out_label);

$out_id    = NULL;
$out_label = NULL;
if (!$stmt->bind_result($out_id, $out_label)) {
    echo "Échec lors du liage des paramètres de sortie : (" . $stmt->errno . ") " . $stmt->error;
}

while ($stmt->fetch()) {
    printf("id = %s (%s), label = %s (%s)\n", $out_id, gettype($out_id), $out_label, gettype($out_label));
}
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
id = 1 (integer), label = a (string)
]]>
    </screen>
   </example>
  </para>
  <para>
   Les requêtes préparées retournent des jeux de résultats non mis en mémoire tampon
   par défaut. Les résultats de la requête ne sont pas implicitement récupérés
   et transférés depuis le serveur vers le client pour une mise en mémoire tampon
   côté client. Le jeu de résultats prend des ressources serveur tant que tous
   les résultats n'ont pas été récupérés par le client. Aussi, il est recommandé
   de les récupérer rapidement. Si un client échoue dans la récupération de
   tous les résultats, ou si le client ferme la requête avant d'avoir récupéré
   toutes les données, les données doivent être récupérées implicitement par
   <literal>mysqli</literal>.
  </para>
  <para>
   Il est également possible de mettre en mémoire tampon les résultats d'une
   requête préparée en utilisant la fonction
   <methodname>mysqli_stmt::store_result</methodname>.
  </para>
  <para>
   <emphasis role="bold">Récupération des résultats en utilisant l'interface mysqli_result</emphasis>
  </para>
  <para>
   Au lieu d'utiliser des résultats liés, les résultats peuvent aussi être récupérées
   via l'interface mysqli_result. La fonction <methodname>mysqli_stmt::get_result</methodname>
   retourne un jeu de résultats mis en mémoire tampon.
  </para>
  <para>
   <example>
    <title>Utilisation de mysqli_result pour récupérer les résultats</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

// Requête non préparée
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label TEXT)");
$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP')");

$stmt = $mysqli->prepare("SELECT id, label FROM test WHERE id = 1");
$stmt->execute();

$result = $stmt->get_result();

var_dump($result->fetch_all(MYSQLI_ASSOC));
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(1) {
  [0]=>
  array(2) {
    ["id"]=>
    int(1)
    ["label"]=>
    string(3) "PHP"
  }
}
]]>
    </screen>
   </example>
  </para>
  <para>
   L'utilisation de l'interface <classname>mysqli_result</classname> offre d'autres avantages
   d'un point de vue flexibilité dans la navigation dans le jeu de résultats côté client.
  </para>
  <para>
   <example>
    <title>Jeu de résultats mis en mémoire tampon pour plus de flexibilité dans la lecture</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

// Requête non préparée
$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT, label TEXT)");
$mysqli->query("INSERT INTO test(id, label) VALUES (1, 'PHP'), (2, 'Java'), (3, 'C++')");

$stmt = $mysqli->prepare("SELECT id, label FROM test");
$stmt->execute();

$result = $stmt->get_result();

for ($row_no = $result->num_rows - 1; $row_no >= 0; $row_no--) {
    $result->data_seek($row_no);
    var_dump($result->fetch_assoc());
}
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(2) {
  ["id"]=>
  int(3)
  ["label"]=>
  string(1) "C++"
}
array(2) {
  ["id"]=>
  int(2)
  ["label"]=>
  string(1) "Java"
}
array(2) {
  ["id"]=>
  int(1)
  ["label"]=>
  string(1) "PHP"
}
]]>
    </screen>
   </example>
  </para>
  <para>
   <emphasis role="bold">Échappement et injection SQL</emphasis>
  </para>
  <para>
   Les variables liées sont envoyées au serveur séparément de la requête,
   ne pouvant ainsi pas interférer avec celle-ci. Le serveur utilise ces valeurs
   directement au moment de l'exécution, après que le template ne soit
   analysé. Les paramètres liés n'ont pas besoin d'être échappés sachant
   qu'ils ne sont jamais placés dans la chaîne de requête directement.
   Une astuce doit être fournie au serveur pour spécifier le type de
   variable liée, afin d'effectuer la conversion appropriée. Voir la
   fonction <methodname>mysqli_stmt::bind_param</methodname> pour plus d'informations.
  </para>
  <para>
   Une telle séparation est souvent considérée comme la seule fonctionnalité
   pour se protéger des injections SQL, mais le même degré de sécurité peut
   être atteint avec les requêtes non-préparées, si toutes les valeurs sont
   correctement formatées. Notez qu'un formattage correct n'est pas la même
   chose qu'un échappement et nécessite plus de logique qu'un simple échappement.
   Aussi, les requêtes préparées sont simplement une méthode plus simple
   et moins prompte aux erreurs concernant cette approche sécuritaire.
  </para>
  <para>
   <emphasis role="bold">Émulation côté client de la préparation d'une requête</emphasis>
  </para>
  <para>
   L'API n'inclut pas d'émulation côté client de la préparation d'une requête.
  </para>
  <para>
   <emphasis role="bold">Voir aussi</emphasis>
  </para>
  <para>
   <simplelist>
    <member><methodname>mysqli::__construct</methodname></member>
    <member><methodname>mysqli::query</methodname></member>
    <member><methodname>mysqli::prepare</methodname></member>
    <member><methodname>mysqli_stmt::prepare</methodname></member>
    <member><methodname>mysqli_stmt::execute</methodname></member>
    <member><methodname>mysqli_stmt::bind_param</methodname></member>
    <member><methodname>mysqli_stmt::bind_result</methodname></member>
   </simplelist>
  </para>
 </section>

 <section xml:id="mysqli.quickstart.stored-procedures">
  <title>Les procédures stockées</title>
  <para>
   La base de données MySQL supporte les procédures stockées. Une procédure stockée
   est une sous routine stockée dans le catalogue de la base de données. Les
   applications peuvent appeler et exécuter une procédure stockée. La
   requête SQL <literal>CALL</literal> est utilisée pour exécuter
   une procédure stockée.
  </para>
  <para>
   <emphasis role="bold">Paramètre</emphasis>
  </para>
  <para>
   Les procédures stockées peuvent avoir des paramètres <literal>IN</literal>,
   <literal>INOUT</literal> and <literal>OUT</literal>, suivant la version de MySQL.
   L'interface mysqli n'a pas de notion spécifique des différents types de paramètres.
  </para>
  <para>
   <emphasis role="bold">Paramètre IN</emphasis>
  </para>
  <para>
   Les paramètres d'entrée sont fournis avec la requête <literal>CALL</literal>.
   Assurez-vous d'échapper correctement les valeurs.
  </para>
  <para>
   <example>
    <title>Appel d'une procédure stockée</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");

$mysqli->query("DROP PROCEDURE IF EXISTS p");
$mysqli->query("CREATE PROCEDURE p(IN id_val INT) BEGIN INSERT INTO test(id) VALUES(id_val); END;");

$mysqli->query("CALL p(1)");

$result = $mysqli->query("SELECT id FROM test");

var_dump($result->fetch_assoc());
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(1) {
  ["id"]=>
  string(1) "1"
}
]]>
    </screen>
   </example>
  </para>
  <para>
   <emphasis role="bold">Paramètre INOUT/OUT</emphasis>
  </para>
  <para>
   Les valeurs des paramètres <literal>INOUT</literal>/<literal>OUT</literal>
   sont accédées en utilisant les variables de session.
  </para>
  <para>
   <example>
    <title>Utilisation des variables de session</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP PROCEDURE IF EXISTS p");
$mysqli->query('CREATE PROCEDURE p(OUT msg VARCHAR(50)) BEGIN SELECT "Hi!" INTO msg; END;');

$mysqli->query("SET @msg = ''");
$mysqli->query("CALL p(@msg)");

$result = $mysqli->query("SELECT @msg as _p_out");

$row = $result->fetch_assoc();
echo $row['_p_out'];
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Hi!
]]>
    </screen>
   </example>
  </para>
  <para>
   Les développeurs d'application et de framework peuvent fournir une API
   plus conviviale utilisant un mix des variables de session et une inspection
   du catalogue de la base de données. Cependant, veuillez garder à l'esprit
   l'impact sur les performances dû à une solution personnalisée basée
   sur l'inspection du catalogue.
  </para>
  <para>
   <emphasis role="bold">Gestion des jeux de résultats</emphasis>
  </para>
  <para>
   Les procédures stockées peuvent retourner des jeux de résultats. Les jeux de
   résultats retournés depuis une procédure stockée ne peuvent être récupérés
   correctement en utilisant la fonction <methodname>mysqli::query</methodname>.
   La fonction <methodname>mysqli::query</methodname> combine l'exécution de la requête
   et la récupération du premier jeu de résultats dans un jeu de résultats mis en
   mémoire tampon, s'il y en a. Cependant, il existe d'autres jeux de résultats
   issus de la procédure stockée qui sont cachés de l'utilisateur et qui
   font que la fonction <methodname>mysqli::query</methodname> échoue lors de la
   récupération des jeux de résultats attendus de l'utilisateur.
  </para>
  <para>
   Les jeux de résultats retournés depuis une procédure stockée sont
   récupérés en utilisant la fonction <methodname>mysqli::real_query</methodname> 
   ou <methodname>mysqli::multi_query</methodname>.
   Ces deux fonctions autorisent la récupération de n'importe quel nombre
   de jeux de résultats retournés par une requête, comme la requête
   <literal>CALL</literal>. L'échec dans la récupération de tous les jeux de résultats
   retournés par une procédure stockée cause une erreur.
  </para>
  <para>
   <example>
    <title>Récupération des résultats issus d'une procédure stockée</title>
    <programlisting role="php">
<![CDATA[
<?php
 
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

$mysqli->query("DROP PROCEDURE IF EXISTS p");
$mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

$mysqli->multi_query("CALL p()");

do {
    if ($res = $mysqli->store_result()) {
        var_dump($result->fetch_all());
        $result->free();
    }
} while ($mysqli->next_result());
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
---
array(3) {
  [0]=>
  array(1) {
    [0]=>
    string(1) "1"
  }
  [1]=>
  array(1) {
    [0]=>
    string(1) "2"
  }
  [2]=>
  array(1) {
    [0]=>
    string(1) "3"
  }
}
---
array(3) {
  [0]=>
  array(1) {
    [0]=>
    string(1) "2"
  }
  [1]=>
  array(1) {
    [0]=>
    string(1) "3"
  }
  [2]=>
  array(1) {
    [0]=>
    string(1) "4"
  }
}
]]>
    </screen>
   </example>
  </para>
  <para>
   <emphasis role="bold">Utilisation des requêtes préparées</emphasis>
  </para>
  <para>
   Aucune gestion spéciale n'est requise lors de l'utilisation de l'interface
   de préparation des requêtes pour récupérer les résultats depuis la même procédure
   stockée que celle ci-dessous. Les interfaces de requête préparée et non préparée
   sont similaires. Veuillez noter que toutes les versions du serveur MySQL ne
   supporte pas la préparation des requêtes SQL <literal>CALL</literal>.
  </para>
  <para>
   <example>
    <title>Procédures stockées et requête préparée</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Échec lors de la connexion à MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

$mysqli->query("DROP PROCEDURE IF EXISTS p");
$mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');

$stmt = $mysqli->prepare("CALL p()");

if (!$stmt->execute()) {
    echo "Échec lors de l'exécution : (" . $stmt->errno . ") " . $stmt->error;
}

do {
    if ($result = $stmt->get_result()) {
        var_dump($result->fetch_all());
        $result->free();
    }
} while ($stmt->next_results());
]]>
    </programlisting>
        &example.outputs;
    <screen>
<![CDATA[
---
array(3) {
  [0]=>
  array(1) {
    [0]=>
    int(1)
  }
  [1]=>
  array(1) {
    [0]=>
    int(2)
  }
  [2]=>
  array(1) {
    [0]=>
    int(3)
  }
}
---
array(3) {
  [0]=>
  array(1) {
    [0]=>
    int(2)
  }
  [1]=>
  array(1) {
    [0]=>
    int(3)
  }
  [2]=>
  array(1) {
    [0]=>
    int(4)
  }
}
]]>
    </screen>
   </example>
  </para>
  <para>
   Bien sûr, l'utilisation de l'API de liage pour la récupération est également supportée.
  </para>
  <para>
   <example>
    <title>Procédures stockées et requête préparée en utilisant l'API de liage</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");
$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3)");

$mysqli->query("DROP PROCEDURE IF EXISTS p");
$mysqli->query('CREATE PROCEDURE p() READS SQL DATA BEGIN SELECT id FROM test; SELECT id + 1 FROM test; END;');
 
$stmt = $mysqli->prepare("CALL p()");
 
$stmt->execute();
 
do {
    if ($stmt->store_result()) {
        $stmt->bind_result($id_out);
        while ($stmt->fetch()) {
            echo "id = $id_out\n";
        }
    }
} while ($stmt->next_result());
]]>
    </programlisting>
        &example.outputs;
    <screen>
<![CDATA[
id = 1
id = 2
id = 3
id = 2
id = 3
id = 4
]]>
    </screen>
   </example>
  </para>
  <para>
   <emphasis role="bold">Voir aussi</emphasis>
  </para>
  <para>
   <simplelist>
    <member><methodname>mysqli::query</methodname></member>
    <member><methodname>mysqli::multi_query</methodname></member>
    <member><methodname>mysqli::next_result</methodname></member>
    <member><methodname>mysqli::more_results</methodname></member>
   </simplelist>
  </para>
 </section>

 <section xml:id="mysqli.quickstart.multiple-statement">
  <title>Requêtes multiples</title>
  <para>
   MySQL autorise optionnellement le fait d'avoir plusieurs requêtes dans une
   seule chaîne de requête mais nécessite une gestion spéciale.
  </para>
  <para>
   Les requêtes multiples ou multirequêtes doivent être exécutées
   avec la fonction <methodname>mysqli::multi_query</methodname>. Les requêtes
   individuelles dans la chaîne de requête sont séparées par un point virgule.
   Ensuite, tous les jeux de résultats retournés par l'exécution des requêtes
   doivent être récupérés.
  </para>
  <para>
   Le serveur MySQL autorise d'avoir des requêtes qui retournent des jeux
   de résultats ainsi que des requêtes qui ne retournent aucun jeu de résultats
   dans la même requête multiple.
  </para>
  <para>
   <example>
    <title>Requêtes multiples</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$mysqli->query("DROP TABLE IF EXISTS test");
$mysqli->query("CREATE TABLE test(id INT)");

$sql = "SELECT COUNT(*) AS _num FROM test;
        INSERT INTO test(id) VALUES (1); 
        SELECT COUNT(*) AS _num FROM test; ";

$mysqli->multi_query($sql);

do {
    if ($result = $mysqli->store_result()) {
        var_dump($result->fetch_all(MYSQLI_ASSOC));
        $result->free();
    }
} while ($mysqli->next_result());
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(1) {
  [0]=>
  array(1) {
    ["_num"]=>
    string(1) "0"
  }
}
array(1) {
  [0]=>
  array(1) {
    ["_num"]=>
    string(1) "1"
  }
}
]]>
    </screen>
   </example>
  </para>
  <para>
   <emphasis role="bold">D'un point de vue de la sécurité</emphasis>
  </para>
  <para>
   Les fonctions <methodname>mysqli::query</methodname> et
   <methodname>mysqli::real_query</methodname> de l'API ne définissent pas de
   drapeau de connexion nécessaire pour l'activation des multirequêtes sur
   le serveur. Un appel supplémentaire à l'API est utilisé pour les multirequêtes
   pour réduire la probabilité d'injection SQL accidentelle. Un attaquant peut
   tenter d'ajouter des requêtes comme
   <literal>; DROP DATABASE mysql</literal> ou <literal>; SELECT SLEEP(999)</literal>.
   Si l'attaquant arrive à ajouter ce genre de SQL dans la chaîne de requête
   mais que <methodname>mysqli::multi_query</methodname> n'est pas utilisé, le serveur
   n'excutera que la première requête, mais pas la seconde représentant la requête SQL
   malicieuse.
  </para>
  <para>
   <example>
    <title>Injection SQL</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");
$result = $mysqli->query("SELECT 1; DROP TABLE mysql.user");
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
PHP Fatal error:  Uncaught mysqli_sql_exception: You have an error in your SQL syntax; 
check the manual that corresponds to your MySQL server version for the right syntax to 
use near 'DROP TABLE mysql.user' at line 1
]]>
    </screen>
   </example>
  </para>
  <para>
   <emphasis role="bold">Prepared statements</emphasis>
  </para>
  <para>
   L'utilisation des requêtes multiples avec des requêtes préparées n'est pas supportée.
  </para>
  <para>
   <emphasis role="bold">Voir aussi</emphasis>
  </para>
  <para>
   <simplelist>
    <member><methodname>mysqli::query</methodname></member>
    <member><methodname>mysqli::multi_query</methodname></member>
    <member><methodname>mysqli_result::next-result</methodname></member>
    <member><methodname>mysqli_result::more-results</methodname></member>
   </simplelist>
  </para>
 </section>

 <section xml:id="mysqli.quickstart.transactions">
  <title>Support API pour les transactions</title>
  <para>
   Le serveur MySQL supporte les transactions suivant le moteur de stockage utilisé.
   Depuis MySQL 5.5, le moteur de stockage par défaut est InnoDB.
   InnoDB a un support complet des transactions ACID.
  </para>
  <para>
   Les transactions peuvent soit être contrôlées en utilisant SQL, soit par des appels API.
   Il est recommandé d'utiliser les appels API pour activer ou désactiver
   le mode <literal>autocommit</literal> et pour valider et annuler les transactions.
  </para>
  <para>
   <example>
    <title>Définir le mode <literal>autocommit</literal> via SQL ou via l'API</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

// Recommandé : utilisation de l'API pour contrôler la configuration des transactions
$mysqli->autocommit(false);

// Ne sera pas monitoré et reconnu par le plugin de réplication et de balance de charge
$mysqli->query('SET AUTOCOMMIT = 0');
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Les paquets de fonctionnalités additionnelles, comme les plugins de réplication
   et de balance de charge peuvent monitorer les appels API. Le plugin de réplication
   offre une sécurité sur les transactions lors de la balance de charge, si
   les transactions sont contrôlées avec des appels API. La sécurité des
   transactions lors de la balance de charge n'est pas disponible si les requêtes
   SQL sont utilisées pour définir le mode <literal>autocommit</literal>, pour valider ou annuler
   une transaction.
  </para>
  <para>
   <example>
    <title>Validation et annulation d'une transaction</title>
    <programlisting role="php">
<![CDATA[
<?php

mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");
$mysqli->autocommit(false);

$mysqli->query("INSERT INTO test(id) VALUES (1)");
$mysqli->rollback();

$mysqli->query("INSERT INTO test(id) VALUES (2)");
$mysqli->commit();
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Veuillez noter que le serveur MySQL ne peut pas annuler toutes les requêtes.
   Quelques requêtes requièrent une validation implicite.
  </para>
  <para>
   <emphasis role="bold">Voir aussi</emphasis>
  </para>
  <para>
   <simplelist>
    <member><methodname>mysqli::autocommit</methodname></member>
    <member><methodname>mysqli::begin_transaction</methodname></member>
    <member><methodname>mysqli::commit</methodname></member>
    <member><methodname>mysqli::rollback</methodname></member>
   </simplelist>
  </para>
 </section>

 <section xml:id="mysqli.quickstart.metadata">
  <title>Les méta-données</title>
  <para>
   Un jeu de résultats MySQL contient des méta-données. Elles décrivent
   les colonnes trouvées dans le jeu de résultats. Toutes les méta-données
   envoyées par MySQL sont accessible via l'interface <literal>mysqli</literal>.
   L'extension n'effectue que très peu (voire, pas du tout) de modification
   sur les informations qu'elle reçoit. Les différences entre les versions MySQL
   ne sont pas identiques.
  </para>
  <para>
   Les méta-données peuvent être consultées via l'interface
   <classname>mysqli_result</classname>.
  </para>
  <para>
   <example>
    <title>
     Accès aux méta-données du jeu de résultats</title>
    <programlisting role="php">
<![CDATA[
<?php

$mysqli = new mysqli("example.com", "user", "password", "database");
if ($mysqli->connect_errno) {
    echo "Échec lors de la connexion à MySQL: (" . $mysqli->connect_errno . ") " . $mysqli->connect_error;
}

$res = $mysqli->query("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
var_dump($res->fetch_fields());
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
array(2) {
  [0]=>
  object(stdClass)#3 (13) {
    ["name"]=>
    string(4) "_one"
    ["orgname"]=>
    string(0) ""
    ["table"]=>
    string(0) ""
    ["orgtable"]=>
    string(0) ""
    ["def"]=>
    string(0) ""
    ["db"]=>
    string(0) ""
    ["catalog"]=>
    string(3) "def"
    ["max_length"]=>
    int(1)
    ["length"]=>
    int(1)
    ["charsetnr"]=>
    int(63)
    ["flags"]=>
    int(32897)
    ["type"]=>
    int(8)
    ["decimals"]=>
    int(0)
  }
  [1]=>
  object(stdClass)#4 (13) {
    ["name"]=>
    string(4) "_two"
    ["orgname"]=>
    string(0) ""
    ["table"]=>
    string(0) ""
    ["orgtable"]=>
    string(0) ""
    ["def"]=>
    string(0) ""
    ["db"]=>
    string(0) ""
    ["catalog"]=>
    string(3) "def"
    ["max_length"]=>
    int(5)
    ["length"]=>
    int(5)
    ["charsetnr"]=>
    int(8)
    ["flags"]=>
    int(1)
    ["type"]=>
    int(253)
    ["decimals"]=>
    int(31)
  }
}
]]>
    </screen>
   </example>
  </para>
  <para>
   <emphasis role="bold">Requêtes préparées</emphasis>
  </para>
  <para>
   Les méta-données des jeux de résultats créés en utilisant des requêtes
   préparées sont accessibles de la même façon. Un gestionnaire
   <classname>mysqli_result</classname> utilisable est retourné par
   la fonction <methodname>mysqli_stmt::result_metadata</methodname>.
  </para>
  <para>
   <example>
    <title>Méta-données via des requêtes préparées</title>
    <programlisting role="php">
<![CDATA[
<?php
 
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("example.com", "user", "password", "database");

$stmt = $mysqli->prepare("SELECT 1 AS _one, 'Hello' AS _two FROM DUAL");
$stmt->execute();

$result = $stmt->result_metadata();
var_dump($result->fetch_fields());
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <emphasis role="bold">Voir aussi</emphasis>
  </para>
  <para>
   <simplelist>
    <member><methodname>mysqli::query</methodname></member>
    <member><methodname>mysqli_result::fetch_fields</methodname></member>
   </simplelist>
  </para>
 </section>
</chapter>