XCVIII. Extension MySQL améliorée

Introduction

L'extension mysqli vous permet d'accéder aux fonctionnalités fournies par MySQL 4.1 et plus. Plus d'informations sur le serveur de bases de données MySQL peuvent être trouvées sur http://www.mysql.com/

La documentation de MySQL peut être trouvée sur http://dev.mysql.com/doc/.

Une partie de cette documentation provient du manuel officiel MySQL avec la permission de MySQL AB.

Pré-requis

Pour faire fonctionner ces fonctions, vous devez compiler PHP avec le support de l'extension MySQLi.

Note : L'extension MySQLi est conçue pour fonctionner avec la version 4.1.3 ou plus de MySQL. Pour les versions plus anciennes, voyez la documentation de l'extension MySQL.

Installation

Pour installer l'extension mysqli pour PHP, utilisez l'option de configuration --with-mysqli=mysql_config_path où mysql_config_path représente l'endroit où se trouve le programme mysql_config qui accompagne les versions de MySQL supérieures à la 4.1. Désactivez aussi l'extension standard MySQL (qui est activée par défaut) en utilisant aussi l'option de configuration --without-mysql. Si vous voulez installer l'extension standard mysql en même temps que l'extension mysqli, la bibliothèque embarquée libmysql distribuée avec PHP ne peut être utilisée. Utilisez à la place les bibliothèques clientes installées par MySQL avec des versions inférieures à la 4.1. Cela forcera PHP à utiliser les bibliothèques du client installées par MySQL pour éviter les conflits.

Configuration à l'exécution

Le comportement de ces fonctions est affecté par la configuration dans le fichier php.ini.

Tableau 1. Options de configuration MySQLi

Nom	Par défaut	Modifiable	Historique
mysqli.max_links	"-1"	PHP_INI_SYSTEM	Disponible depuis PHP 5.0.0.
mysqli.default_port	NULL	PHP_INI_ALL	Disponible depuis PHP 5.0.0.
mysqli.default_socket	NULL	PHP_INI_ALL	Disponible depuis PHP 5.0.0.
mysqli.default_host	NULL	PHP_INI_ALL	Disponible depuis PHP 5.0.0.
mysqli.default_user	NULL	PHP_INI_ALL	Disponible depuis PHP 5.0.0.
mysqli.default_pw	NULL	PHP_INI_ALL	Disponible depuis PHP 5.0.0.

Pour plus de détails sur les constantes PHP_INI_*, reportez-vous à Annexe G.

Voici un éclaircissement sur l'utilisation des directives de configuration.

mysqli.max_links entier: Le nombre maximal de connexions MySQL par processus, incluant les connexions persistantes.
mysqli.default_port string: Le numéro par défaut de port TCP à utiliser lors de la connexion au serveur si aucun autre port n'est fourni. S'il n'est pas défini, le port sera obtenu à partir de la variable d'environnement MYSQL_TCP_PORT, l'entrée mysql-tcp dans /etc/services ou la constante de compilation MYSQL_PORT, dans cet ordre. Win32 n'utilisera que la constante MYSQL_PORT.
mysqli.default_socket string: Le nom par défaut de la socket à utiliser lors des connexions locales au serveur si aucun autre nom n'est fourni.
mysqli.default_host string: Le serveur par défaut à utiliser lors de la connexion à un serveur si aucun autre hôte n'est fourni. Ne s'applique pas avec le safe mode.
mysqli.default_user string: Le nom d'utilisateur par défaut à utiliser lors de la connexion à un serveur si aucun autre nom n'est fourni. Ne s'applique pas avec le safe mode.
mysqli.default_pw string: Le mot de passe par défaut à utiliser lors de la connexion à un serveur si aucun autre mot de passe n'est fourni. Ne s'applique pas avec le safe mode.

Classes pré-définies

mysqli

Représente la connexion entre PHP et le serveur MySQL.

Constructeur

mysqli - construit un nouvel objet mysqli

Méthodes

autocommit - Active ou désactive l'auto-commit
change_user - Change l'utilisateur de la connexion
character_set_name - Retourne le jeu de caractères par défaut de la connexion
close - Ferme une connexion ouverte
commit - Valide la transaction courante
connect - Ouvre une nouvelle connexion au serveur MySQL
debug - Effectue des opérations de débogage
dump_debug_info - Affiche les informations de débogage
get_client_info - Retourne la version du client
get_host_info - Retourne le type de connexion utilisé
get_server_info - Retourne la version du serveur MySQL
get_server_version - Retourne la version du serveur MySQL
init - Initialise un objet mysqli
info - Lit les informations concernant la dernière requête
kill - Tente de terminer un thread serveur
multi_query - Exécute une requête multiple
more_results - Vérifie si d'autres résultats existent après une commande multiple
next_result - Lit le prochain résultat d'une commande multiple
options - Modifie des options
ping - Pinge la connexion au serveur ou se reconnecte si elle est morte
prepare - Prépare une requête SQL
query - Exécute une requête SQL
real_connect - Tente de se connecter au serveur MySQL
escape_string - Protège les caractères spéciaux dans une chaîne
rollback - Annule la transaction courante
select_db - Sélectionne la base de données par défaut
set_charset - Définit le jeu de caractères par défaut du client
ssl_set - Configure les paramètres SSL
stat - Lit le statut courant du système
stmt_init - Initialise une commande pour utilisation avec mysqli_stmt_prepare
store_result - Lit le jeu de résultat de la dernière requête
thread_safe - Indique si la sécurité du thread est activée
use_result - Transfère un résultat non-bufferisé

Propriétés

affected_rows - Lit le nombre de lignes affectées par la dernière opération
client_info - Retourne la version cliente de MySQL en tant que chaîne de caractères
client_version - Retourne la version cliente de MySQL en tant qu'entier
errno - Retourne le code d'erreur du dernier appel de fonction
error - Retourne le message d'erreur du dernier appel de fonction
field_count - Retourne le nombre de colonnes de la dernière commande
host_info - Retourne une chaîne décrivant le type de connexion utilisé
info - Lit les informations sur la dernière commande exécutée
insert_id - Retourne le dernier identifiant généré
protocol_version - Retourne la version du protocole MySQL utilisé
server_info - Retourne une chaîne de caractères qui représente le numéro de version du serveur
server_version - Retourne le numéro de version du serveur en tant qu'entier
sqlstate - Retourne une chaîne contenant le code d'erreur SQLSTATE
thread_id - Retourne l'identifiant de thread de la connexion courante
warning_count - Retourne le nombre d'alertes générées durant l'exécution de la dernière commande SQL

mysqli_stmt

Représente une commande préparée.

Méthodes

bind_param - Associe des variables à une commande préparée
bind_result - Associe des variables à un résultat
close - Termine une commande préparée
data_seek - Place le curseur à une ligne arbitraire dans un jeu de résultat
execute - Exécute une commande préparée
fetch - Lit une ligne de résultat dans des variables associées
free_result - Libère le résultat de la mémoire
prepare - Prépare une commande SQL
reset - annule une commande SQL
result_metadata - Lit un résultat d'une commande préparée
send_long_data - Envoie les données par bloc
store_result - Bufferise complètement le résultat d'une commande préparée

Propriétés

affected_rows - Retourne le nombre de lignes affectées par la dernière commande SQL
errno - Retourne le code d'erreur de la dernière commande
error - Retourne le message d'erreur de la dernière commande
field_count - Retourne le nombre de colonnes dans un jeu de résultats
id - Retourne l'identifiant de la requête
insert_id - Retourne la valeur générée pour une colonne AUTO_INCREMENT par la requête préparée
num_rows - Retourne le nombre de lignes dans le jeu de résultats
param_count - Retourne le nombre de paramètres nécessaires pour une commande préparée
sqlstate - Retourne une chaîne contenant le code d'erreur SQLSTATE de la dernière commande

mysqli_result

Représente le résultat retourné par le serveur.

Méthodes

close - Termine le jeu de résultat MySQL
data_seek - Déplace le pointeur de lignes de résultat
fetch_array - Lit une ligne de résultat dans un tableau associatif ou numérique
fetch_assoc - Lit une ligne de résultat dans un tableau associatif
fetch_field - Lit les informations de colonnes dans un résultat
fetch_fields - Lit les informations de toutes les colonnes d'un résultat
fetch_field_direct - Lit les informations de colonne
fetch_object - Lit une ligne de résultat dans un objet
fetch_row - Lit une ligne de résultat dans un tableau numérique
field_seek - Place le pointeur de résultat à un offset valide
free_result - Libère le résultat de la mémoire

Propriétés

current_field - Retourne la position du pointeur de résultat
field_count - Retourne le nombre de champs du résultat
lengths - Retourne un tableau avec les tailles de colonnes
num_rows - Retourne le nombre de lignes du résultat
type - Retourne MYSQLI_STORE_RESULT ou MYSQLI_USE_RESULT

Constantes pré-définies

Tableau 2. Constantes MySQLi

Nom	Description
`MYSQLI_READ_DEFAULT_GROUP` (entier)	Lit les options dans le groupe `my.cnf' ou dans le fichier spécifié par `MYSQLI_READ_DEFAULT_FILE`
`MYSQLI_READ_DEFAULT_FILE` (entier)	Lit les options dans le fichier spécifié, plutôt que dans `my.cnf`
`MYSQLI_OPT_CONNECT_TIMEOUT` (entier)	Durée d'expiration de la connexion, en secondes
`MYSQLI_OPT_LOCAL_INFILE` (entier)	Active la commande `LOAD LOCAL INFILE`
`MYSQLI_INIT_COMMAND` (entier)	Commande à exécuter lors de la connexion au serveur MySQL. Cette commande sera exécutée automatiquement lors de la reconnexion au serveur.
`MYSQLI_CLIENT_SSL` (entier)	Utilise le protocole SSL (chiffrement). Cette option ne doit pas être activée par un programme : elle doit être activée en interne, par la bibliothèque MySQL.
`MYSQLI_CLIENT_COMPRESS` (entier)	Utilise le protocole compressé.
`MYSQLI_CLIENT_INTERACTIVE` (entier)	Permet `interactive_timeout` secondes (au lieu de `wait_timeout` secondes) d'inactivité avant de fermer la connexion. La valeur de la variable `wait_timeout` du client prendra la valeur de `interactive_timeout`.
`MYSQLI_CLIENT_IGNORE_SPACE` (entier)	Permet les espaces après un nom de fonction. Cela fait de tous les noms de fonctions, des mots réservés.
`MYSQLI_CLIENT_NO_SCHEMA` (entier)	Interdit la syntaxe db_name.tbl_name.col_name.
`MYSQLI_CLIENT_MULTI_QUERIES` (entier)
`MYSQLI_STORE_RESULT` (entier)	Pour les résultats mis en tampon.
`MYSQLI_USE_RESULT` (entier)	Pour les résultats non-mis en tampon.
`MYSQLI_ASSOC` (entier)	Les colonnes sont retournées dans le tableau, avec leurs noms comme index.
`MYSQLI_NUM` (entier)	Les colonnes sont retournées dans le tableau, avec leurs numéros comme index.
`MYSQLI_BOTH` (entier)	Les colonnes sont retournées dans le tableau, avec leurs noms et leurs numéros comme index.
`MYSQLI_NOT_NULL_FLAG` (entier)	Indique qu'un champ est défini comme `NOT NULL`
`MYSQLI_PRI_KEY_FLAG` (entier)	Le champ est une clé primaire.
`MYSQLI_UNIQUE_KEY_FLAG` (entier)	Le champ est un index unique.
`MYSQLI_MULTIPLE_KEY_FLAG` (entier)	Le champ fait partie d'un index.
`MYSQLI_BLOB_FLAG` (entier)	Le champ est de type `BLOB`
`MYSQLI_UNSIGNED_FLAG` (entier)	Le champ est de type `UNSIGNED`
`MYSQLI_ZEROFILL_FLAG` (entier)	Le champ est de type `ZEROFILL`
`MYSQLI_AUTO_INCREMENT_FLAG` (entier)	Le champ est de type `AUTO_INCREMENT`
`MYSQLI_TIMESTAMP_FLAG` (entier)	Le champ est de type `TIMESTAMP`
`MYSQLI_SET_FLAG` (entier)	Le champ est de type `SET`
`MYSQLI_NUM_FLAG` (entier)	Le champ est de type `NUMERIC`
`MYSQLI_PART_KEY_FLAG` (entier)	Le champ fait partie d'un index multiple
`MYSQLI_GROUP_FLAG` (entier)	Le champ fait partie de la clause `GROUP BY`
`MYSQLI_TYPE_DECIMAL` (entier)	Le champ est de type `DECIMAL`
`MYSQLI_TYPE_NEWDECIMAL` (entier)	Le champ est de type `DECIMAL` ou `NUMERIC` (MySQL 5.0.3 et supérieur)
`MYSQLI_TYPE_BIT` (entier)	Le champ est de type `BIT` (MySQL 5.0.3 et supérieur)
`MYSQLI_TYPE_TINY` (entier)	Le champ est de type `TINYINT`
`MYSQLI_TYPE_SHORT` (entier)	Le champ est de type `INT`
`MYSQLI_TYPE_LONG` (entier)	Le champ est de type `INT`
`MYSQLI_TYPE_FLOAT` (entier)	Le champ est de type `FLOAT`
`MYSQLI_TYPE_DOUBLE` (entier)	Le champ est de type `DOUBLE`
`MYSQLI_TYPE_NULL` (entier)	Le champ est de type `DEFAULT NULL`
`MYSQLI_TYPE_TIMESTAMP` (entier)	Le champ est de type `TIMESTAMP`
`MYSQLI_TYPE_LONGLONG` (entier)	Le champ est de type `BIGINT`
`MYSQLI_TYPE_INT24` (entier)	Le champ est de type `MEDIUMINT`
`MYSQLI_TYPE_DATE` (entier)	Le champ est de type `DATE`
`MYSQLI_TYPE_TIME` (entier)	Le champ est de type `TIME`
`MYSQLI_TYPE_DATETIME` (entier)	Le champ est de type `DATETIME`
`MYSQLI_TYPE_YEAR` (entier)	Le champ est de type `YEAR`
`MYSQLI_TYPE_NEWDATE` (entier)	Le champ est de type `DATE`
`MYSQLI_TYPE_ENUM` (entier)	Le champ est de type `ENUM`
`MYSQLI_TYPE_SET` (entier)	Le champ est de type `SET`
`MYSQLI_TYPE_TINY_BLOB` (entier)	Le champ est de type `TINYBLOB`
`MYSQLI_TYPE_MEDIUM_BLOB` (entier)	Le champ est de type `MEDIUMBLOB`
`MYSQLI_TYPE_LONG_BLOB` (entier)	Le champ est de type `LONGBLOB`
`MYSQLI_TYPE_BLOB` (entier)	Le champ est de type `BLOB`
`MYSQLI_TYPE_VAR_STRING` (entier)	Le champ est de type `VARCHAR`
`MYSQLI_TYPE_STRING` (entier)	Le champ est de type `CHAR`
`MYSQLI_TYPE_GEOMETRY` (entier)	Le champ est de type `GEOMETRY`
`MYSQLI_NEED_DATA` (entier)	Il reste des variables à relier
`MYSQLI_NO_DATA` (entier)	Il n'y a plus de variables à relier
`MYSQLI_DATA_TRUNCATED` (integer)	Les données ont été tronquées. Disponible depuis PHP 5.1.0 et MySQL 5.0.5.

Exemples

Tous les exemples dans la documentation MySQLI utilisent la base de données "world" provenant de MySQL AB. La base de données "world" peut être trouvée ici : http://dev.mysql.com/get/Downloads/Manual/world.sql.gz/from/pick

Table des matières
mysqli_affected_rows -- Retourne le nombre de lignes affectées par la dernière opération MySQL
mysqli_autocommit -- Active ou désactive le mode auto-commit
mysqli_bind_param -- Alias de mysqli_stmt_bind_param()
mysqli_bind_result -- Alias de mysqli_stmt_bind_result()
mysqli_change_user -- Change l'utilisateur de la connexion spécifiée
mysqli_character_set_name -- Retourne le jeu de caractères courant pour la connexion
mysqli_client_encoding -- Alias de mysqli_character_set_name()
mysqli_close -- Ferme une connexion
mysqli_commit -- Valide la transaction courante
mysqli_connect_errno -- Retourne le code d'erreur de la connexion MySQL
mysqli_connect_error -- Retourne le message d'erreur de connexion MySQL
mysqli_connect -- Ouvre une connexion à un serveur MySQL
mysqli_data_seek -- Déplace le pointeur interne de résultat
mysqli_debug -- Effectue des actions de débogage
mysqli_disable_reads_from_master -- Désactive la lecture depuis le maître
mysqli_disable_rpl_parse -- Désactive le parseur RPL
mysqli_dump_debug_info -- Écrit les informations de débogage dans les logs
mysqli_embedded_server_end --
mysqli_embedded_server_start --
mysqli_enable_reads_from_master -- Active la lecture depuis le maître
mysqli_enable_rpl_parse -- Active le parseur RPL
mysqli_errno -- Retourne un code d'erreur pour la dernière commande MySQL
mysqli_error -- Retourne une chaîne décrivant la dernière erreur
mysqli_escape_string -- Alias de mysqli_real_escape_string()
mysqli_execute -- Alias de mysqli_stmt_execute()
mysqli_fetch_array -- Retourne une ligne de résultat sous la forme d'un tableau associatif, d'un tableau indexé, ou les deux
mysqli_fetch_assoc -- Récupère une ligne de résultat sous forme de tableau associatif
mysqli_fetch_field_direct -- Récupère les données métas d'un champ unique
mysqli_fetch_field -- Retourne le prochain champs dans le jeu de résultats
mysqli_fetch_fields -- Retourne un tableau d'objets représentant les champs dans le résultat
mysqli_fetch_lengths -- Retourne la longueur des colonnes de la ligne courante du jeu de résultats
mysqli_fetch_object -- Retourne la ligne courante d'un jeu de résultat sous forme d'objet
mysqli_fetch_row -- Récupère une ligne de résultat sous forme de tableau indexé
mysqli_fetch -- Alias de mysqli_stmt_fetch()
mysqli_field_count -- Retourne le nombre de colonnes pour la dernière requête
mysqli_field_seek -- Déplace le pointeur de résultat sur le champs spécifié
mysqli_field_tell -- Retourne la position du champs courant dans un pointeur de résultat
mysqli_free_result -- Libère la mémoire associée à un résultat
mysqli_get_charset -- Retourne un objet contenant le jeu de caractères
mysqli_get_client_info -- Retourne une chaîne contenant la version du client MySQL
mysqli_get_client_version -- Lit les informations du client MySQL
mysqli_get_host_info -- Retourne une chaîne contenant le type de connexion utilisée
mysqli_get_metadata -- Alias de mysqli_stmt_result_metadata()
mysqli_get_proto_info -- Retourne la version du protocole MySQL utilisé
mysqli_get_server_info -- Retourne la version du serveur MySQL
mysqli_get_server_version -- Retourne un entier représentant la version du serveur MySQL
mysqli_get_warnings --
mysqli_info -- Retourne des informations à propos de la dernière requête exécutée
mysqli_init -- Initialise MySQLi et retourne une ressource à utiliser avec mysqli_real_connect()
mysqli_insert_id -- Retourne l'identifiant automatiquement généré par la dernière requête
mysqli_kill -- Demande au serveur de terminer un thread MySQL
mysqli_master_query -- Force l'exécution d'une requête sur le maître dans une configuration maître/esclave (master/slave)
mysqli_more_results -- Vérifie s'il y a d'autres jeux de résultats MySQL disponibles
mysqli_multi_query -- Exécute une requête MySQL multiple
mysqli_next_result -- Prépare le prochain résultat d'une requête multiple
mysqli_num_fields -- Retourne le nombre de champs dans un résultat
mysqli_num_rows -- Retourne le nombre de lignes dans un résultat
mysqli_options -- Définit les options
mysqli_param_count -- Alias de mysqli_stmt_param_count()
mysqli_ping -- Ping la connexion au serveur et reconnecte si elle n'existe plus
mysqli_prepare -- Prépare une requête SQL pour l'exécution
mysqli_query -- Exécute une requête sur la base de données
mysqli_real_connect -- Ouvre une connexion à un serveur MySQL
mysqli_real_escape_string -- Protège les caractères spéciaux d'une chaîne pour l'utiliser dans une requête SQL, en prenant en compte le jeu de caractères courant de la connexion
mysqli_real_query -- Exécute une requête SQL
mysqli_report -- Active ou désactive les fonctions de rapport interne
mysqli_rollback -- Annule la transaction courante
mysqli_rpl_parse_enabled -- Vérifie si l'analyseur RPL est activé
mysqli_rpl_probe -- Sonde le RPL
mysqli_rpl_query_type -- Retourne le type de requête RPL
mysqli_select_db -- Sélectionne une base de données par défaut pour les requêtes
mysqli_send_long_data -- Alias de mysqli_stmt_send_long_data()
mysqli_send_query -- Envoie la requête et retourne
mysqli_server_end -- Eteint le serveur embarqué
mysqli_server_init -- Initialise le serveur MySQL intégré
mysqli_set_charset -- Définit le jeu de caractères par défaut du client
mysqli_set_local_infile_default -- Rétablit le gestionnaire par défaut pour la commande LOAD LOCAL INFILE
mysqli_set_local_infile_handler -- Définit une fonction de callback pour la commande LOAD DATA LOCAL INFILE
mysqli_set_opt -- Alias de mysqli_options()
mysqli_slave_query -- Force l'exécution de la requête sur un serveur esclave pour une configuration maître/esclave
mysqli_sqlstate -- Retourne l'erreur SQLSTATE de la dernière opération MySQL
mysqli_ssl_set -- Utilisée pour établir une connexion sécurisée avec SSL
mysqli_stat -- Obtient le statut courant du système
mysqli_stmt_affected_rows -- Retourne le nombre total de lignes modifiées, effacées ou insérées par la dernière requête
mysqli_stmt_attr_get --
mysqli_stmt_attr_set --
mysqli_stmt_bind_param -- Lie des variables à une requête MySQL
mysqli_stmt_bind_result -- Lie des variables à un jeu de résultats
mysqli_stmt_close -- Ferme une requête préparée
mysqli_stmt_data_seek -- Déplace le pointeur de résultat MySQL
mysqli_stmt_errno -- Retourne un code erreur pour la dernière requête
mysqli_stmt_error -- Retourne une description de la dernière erreur de traitement
mysqli_stmt_execute -- Exécute une requête préparée
mysqli_stmt_fetch -- Lit des résultats depuis une requête MySQL préparée dans des variables liées
mysqli_stmt_field_count -- Retourne le nombre de champs présent dans la requête donnée
mysqli_stmt_free_result -- Libère le résultat MySQL de la mémoire
mysqli_stmt_get_warnings --
mysqli_stmt_init -- Initialise une commande MySQL
mysqli_stmt_insert_id -- Récupère l'ID généré par la dernière requête INSERT
mysqli_stmt_num_rows -- Retourne le nombre de lignes d'un résultat MySQL
mysqli_stmt_param_count -- Retourne le nombre de paramètres d'une commande MySQL
mysqli_stmt_prepare -- Prépare une requête SQL pour l'exécution
mysqli_stmt_reset -- Annule une requête préparée
mysqli_stmt_result_metadata -- Retourne les méta-données de préparation de requête MySQL
mysqli_stmt_send_long_data -- Envoie des données MySQL par paquets
mysqli_stmt_sqlstate -- Retourne le code SQLSTATE de la dernière opération MySQL
mysqli_stmt_store_result -- Récupère un jeu de résultats depuis une requête préparée
mysqli_store_result -- Transfère un jeu de résultats à partir de la dernière requête
mysqli_thread_id -- Retourne l'identifiant du thread pour la connexion courante
mysqli_thread_safe -- Indique si le thread safety est donné ou non
mysqli_use_result -- Initialise la récupération d'un jeu de résultats
mysqli_warning_count -- Retourne le nombre d'avertissements générés par la dernière requête